diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000000000000000000000000000000000000..9ce8a537de5f2c96290caf3fce594a9e32707640 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,5 @@ +root = true + +[*] +end_of_line = lf +trim_trailing_whitespace = true diff --git a/.gitattributes b/.gitattributes index a6344aac8c09253b3b630fb776ae94478aa0275b..e6d53a66bc3650d7b6fa1a7de399ad6166c86c67 100644 --- a/.gitattributes +++ b/.gitattributes @@ -33,3 +33,649 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text *.zip filter=lfs diff=lfs merge=lfs -text *.zst filter=lfs diff=lfs merge=lfs -text *tfevents* filter=lfs diff=lfs merge=lfs -text +api/extension-capabilities/images/extending-workbench/workbench-contribution.png filter=lfs diff=lfs merge=lfs -text +api/extension-capabilities/images/theming/color-theme.png filter=lfs diff=lfs merge=lfs -text +api/extension-capabilities/images/theming/icon-theme.png filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/color-theme/color-setting.png filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/color-theme/tm-inspector.png filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/debugger-extension/debug-features.png filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/debugger-extension/debugger-extension-server.png filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/debugger-extension/mock-debug.gif filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/tree-view/view-container.png filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/basics-developer_tools.png filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/basics-drag.gif filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/basics-html.png filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/basics-ondidchangeviewstate.gif filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/basics-restore.gif filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/basics-single_panel.gif filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/basics-update.gif filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/persistence-retrain.gif filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/scripts-basic.gif filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/scripts-extension_to_webview.gif filter=lfs diff=lfs merge=lfs -text +api/extension-guides/images/webview/scripts-webview_to_extension.gif filter=lfs diff=lfs merge=lfs -text +api/get-started/images/your-first-extension/debug.mp4 filter=lfs diff=lfs merge=lfs -text +api/get-started/images/your-first-extension/launch.mp4 filter=lfs diff=lfs merge=lfs -text +api/get-started/images/your-first-extension/reload.mp4 filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-server-extension-guide/debugging-client.png filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-server-extension-guide/debugging-server.png filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-server-extension-guide/lsp-inspector.png filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-server-extension-guide/lsp-log.png filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/code-completion.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/code-lens[[:space:]]copy.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/code-lens.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/document-highlights.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/document-symbols.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/find-references.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/format-document-range.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/format-document.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/goto-definition.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/hovers.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/quick-fixes.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/rename.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/language-support/workspace-symbols.gif filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/syntax-highlighting/yaml-grammar.png filter=lfs diff=lfs merge=lfs -text +api/language-extensions/images/syntax-highlighting/yo-new-language-questions.png filter=lfs diff=lfs merge=lfs -text +api/references/images/contribution-points/menus.png filter=lfs diff=lfs merge=lfs -text +api/working-with-extensions/images/continuous-integration/pipelines.png filter=lfs diff=lfs merge=lfs -text +api/working-with-extensions/images/publishing-extension/token1.png filter=lfs diff=lfs merge=lfs -text +api/working-with-extensions/images/publishing-extension/token2.png filter=lfs diff=lfs merge=lfs -text +api/working-with-extensions/images/publishing-extension/token3.png filter=lfs diff=lfs merge=lfs -text +api/working-with-extensions/images/publishing-extension/token4.png filter=lfs diff=lfs merge=lfs -text +api/working-with-extensions/images/testing-extension/pipelines.png filter=lfs diff=lfs merge=lfs -text +api/working-with-extensions/images/testing-extension/test-output.png filter=lfs diff=lfs merge=lfs -text +blogs/2016/02/23/chrome-debugger-demo.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/03/11/change-case_demo.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/03/11/ruby_debugging.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/03/11/yo_demo.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/04/14/header.png filter=lfs diff=lfs merge=lfs -text +blogs/2016/04/14/installs.png filter=lfs diff=lfs merge=lfs -text +blogs/2016/05/04/auto-complete.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/05/04/complexity-codelens.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/05/04/debugger-for-edge.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/05/04/svg-viewer.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/07/29/annotate-animation.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/07/29/git-history-animation.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/07/29/partial-diff.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/07/29/share-code-animation.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/08/19/github_reaction.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/08/22/ios-debugger-demo.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/09/14/npm_intellisense.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/10/31/chrome_debugger.png filter=lfs diff=lfs merge=lfs -text +blogs/2016/10/31/document_this.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/10/31/git_project_manager.gif filter=lfs diff=lfs merge=lfs -text +blogs/2016/12/12/theme-preview.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/01/15/AppSettings.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/01/15/AzurePortal.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/01/15/ChromePause.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/01/15/CreateDocDB.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/01/15/Debugger.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/01/15/Dockerfile.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/02/08/TM-scope-inspector.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/02/08/tokenization-2.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/02/12/code_lens.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/02/12/manifest_preview.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/02/12/preview_gitlens.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/04/10/close_html_xml_tag.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/06/20/themes-ayu.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/06/20/themes-nord.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/06/20/themes-sapphire.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/06/20/vscode-great-icons.jpg filter=lfs diff=lfs merge=lfs -text +blogs/2017/08/07/emmet.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/09/28/java-debug.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/10/03/60fps.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/10/03/paint-flashing.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/10/03/texture-atlas.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/10/24/stablewithblue.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/11/15/ls-dual-screen.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/11/15/ls-social-resized.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/11/15/ls-social.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/11/15/vs-code-ls-session.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/11/15/vs-code-ls-session2.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/12/20/break_on_load_after.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/12/20/code_chrome_devtools.gif filter=lfs diff=lfs merge=lfs -text +blogs/2017/12/20/social_paused.png filter=lfs diff=lfs merge=lfs -text +blogs/2017/12/20/sync_stepping.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/03/23/piece-tree.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/03/23/write.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/04/25/Beautify.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/04/25/BingDiagram.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/04/25/FormatOnKeypress.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/04/25/OpenFilesOnLeft.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/04/25/SocialImg.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/04/25/ZoomScrollWheel.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/05/07/lsp.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/05/07/shared-terminal.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/07/12/auto-attach.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/07/12/debug-extension-api.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/07/12/debugger.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/07/12/debugging_architecture.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/07/12/logpoints.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/07/12/npm_scripts.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/09/10/github_pr_hero.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/09/10/github_pr_overview.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/09/12/build.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/09/12/pr.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/09/12/slack.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/09/12/tweet.png filter=lfs diff=lfs merge=lfs -text +blogs/2018/12/04/CPlusPlus.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/12/04/CSharp.gif filter=lfs diff=lfs merge=lfs -text +blogs/2018/12/04/CrossRepoJump.gif filter=lfs diff=lfs merge=lfs -text +docs/azure/images/docker/dockercommands.gif filter=lfs diff=lfs merge=lfs -text +docs/azure/images/docker/generateFiles.gif filter=lfs diff=lfs merge=lfs -text +docs/azure/images/kubernetes/check-status.gif filter=lfs diff=lfs merge=lfs -text +docs/azure/images/kubernetes/create-k8s.gif filter=lfs diff=lfs merge=lfs -text +docs/azure/images/kubernetes/create-manifest.gif filter=lfs diff=lfs merge=lfs -text +docs/azure/images/kubernetes/install-kubernetes.png filter=lfs diff=lfs merge=lfs -text +docs/azure/images/kubernetes/start-deployment.gif filter=lfs diff=lfs merge=lfs -text +docs/azure/images/remote-debugging/remote-breakpoint.png filter=lfs diff=lfs merge=lfs -text +docs/azure/images/remote-debugging/start-remote-debugging.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/accessibility/zoomed-in.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/codebasics/CodeBasics.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/codebasics/column-select.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/codebasics/multicursor-word.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/codebasics/multicursor.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/debugging/Debugging.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/debugging/add-config.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/debugging/hitCount.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/debugging/launch-json-intellisense.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/debugging/log-points.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/emmet/emmet-multi-cursor.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/emmet/emmet-vendor-prefix.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/emmet/emmet.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/extension-gallery/disable-extension.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/extension-gallery/enable-extension.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/extension-gallery/extension-search-categories.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/extension-gallery/extensions-disable-all.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/extension-gallery/extensions-disable.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/extension-gallery/extensions-popular.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/extension-gallery/extensions-python.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/extension-gallery/uninstall-extension.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/intellisense/localitybonus.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/intellisense/tabCompletion.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/multi-root-workspaces/multiple-scm-providers.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/multi-root-workspaces/settings-dropdown.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/refactoring/ts-extract-local.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/tasks/run-input-example.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/userdefinedsnippets/ajax-snippet.gif filter=lfs diff=lfs merge=lfs -text +docs/editor/images/versioncontrol/GitHub-clone-dialog.png filter=lfs diff=lfs merge=lfs -text +docs/editor/images/versioncontrol/scm.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/keybinding/keyboard-shortcuts.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/settings/lang-based-settings.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/themes/built-in-themes.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/themes/theme-activitybar.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/Errors_Warnings.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/InstallExtensions.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/KeyboardShortcuts.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/OpenCommandPalatte.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/PreviewFileIconThemes.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/PreviewThemes.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/QuickOpen.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/add_cursor_current_selection.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/add_cursor_current_selection_one_by_one.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/change_syntax.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/code_folding.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/code_formatting.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/column-select.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/command_p.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/configure_debug.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/create_open_file.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/debug_data_inspection.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/emmet_syntax.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/find_all_references.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/find_by_symbol.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/git_side_by_side.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/git_stage_all.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/goto_definition.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/intellisense.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/markdown-preview-side-by-side.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/move_line.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/multicursor.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/navigate_editors.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/navigate_history.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/navigate_to_line.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/node_debug.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/package_json_intellisense.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/peek.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/rename_symbol.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/shrink_expand_selection.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/split_editor.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/switch_branches.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/task_runner.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/toggle_side_bar.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/trim_whitespace.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/undo_last_commit.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/tips-and-tricks/zen_mode.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/userinterface/grid-dnd.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/userinterface/grid-layout-menu.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/userinterface/grid-layout.gif filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/userinterface/hero.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/userinterface/sidebyside.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/userinterface/tabs-editor-groups.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/userinterface/view-management.png filter=lfs diff=lfs merge=lfs -text +docs/getstarted/images/userinterface/workspace-settings.png filter=lfs diff=lfs merge=lfs -text +docs/introvideos/images/opengraph/introvideos.png filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-azurefunctions/add-functions.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-azurefunctions/debug-functions.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-azurefunctions/deploy-functions.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/attach-source.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/conditional-bp.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/current-file.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/cwd-env.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/expression-evaluation.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/hcr.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/java-debug.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/java9.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/junit.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/launch-in-terminal.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/logpoints.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/resolve-main.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/single-file.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/step-filter.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-debugging/test-explorer.png filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/Intellisense(Intellicode).gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/checkstyle.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/code-editing.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/getter-setter.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/intellicode.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/quick-fix.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/refactor.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/rename.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/search-in-file.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/search-in-workspace.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-editing/spring-navigation.png filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/create-project.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/hierarchical.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/maven-archetype.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/maven-effective-pom.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/maven-explorer.png filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/maven-history.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/maven-plugin-goal.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/maven-pom-editing.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/maven-run.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/multiple-source.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/package-viewer.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-project/standalone.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-spring-boot/spring-code-edit.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-spring-boot/spring-dashboard.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-spring-boot/spring-initializr-edit.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-spring-boot/spring-initializr.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-testing/report.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-testing/test-junit5.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-testing/testng.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-tomcat-jetty/jetty.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-tomcat-jetty/tomcat-create-server.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-tomcat-jetty/tomcat.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-tutorial/create-file.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-tutorial/edit-code.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-tutorial/run-debug.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-webapp/clone-repository.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-webapp/debugging-status-bar.png filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-webapp/debugging.png filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-webapp/deploy-webapp.png filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-webapp/install-extensions.gif filter=lfs diff=lfs merge=lfs -text +docs/java/images/java-webapp/run-spring-boot.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/Markdown/double-click-preview-switch.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/Markdown/md-dynamic-preview.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/Markdown/preview-scroll-sync.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/Markdown/security-alert.png filter=lfs diff=lfs merge=lfs -text +docs/languages/images/cpp/includepath.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/cpp/languages_cpp.png filter=lfs diff=lfs merge=lfs -text +docs/languages/images/csharp/languages_csharp.png filter=lfs diff=lfs merge=lfs -text +docs/languages/images/html/auto-close1.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/html/emmetsnippet.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/java/intellisense.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/java/java-debug.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/java/java-test-explorer.png filter=lfs diff=lfs merge=lfs -text +docs/languages/images/java/java-test.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/java/package-viewer.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/java/resolve-main.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/java/testng.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/java/tomcat.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/java/vscode-java.0.0.1.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/javascript/checkjs-example.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/javascript/intellisense-placeholder.png filter=lfs diff=lfs merge=lfs -text +docs/languages/images/javascript/intellisense.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/javascript/jsx.png filter=lfs diff=lfs merge=lfs -text +docs/languages/images/javascript/organize-imports.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/javascript/overview.png filter=lfs diff=lfs merge=lfs -text +docs/languages/images/javascript/tag-complete.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/javascript/update-imports-placeholder.png filter=lfs diff=lfs merge=lfs -text +docs/languages/images/javascript/update-imports.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/powershell/codeLensFuncRef.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/powershell/codeLensPesterDebug.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/powershell/codeLensPesterSymbol.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/python/feature_showcase.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/python/jupyter.png filter=lfs diff=lfs merge=lfs -text +docs/languages/images/python/python-debugging.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/python/python-editing.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/python/python-linting.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/python/python-snippets.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/tsql/execute.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/tsql/intellisense.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/tsql/linting.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/tsql/peekdefinition.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/tsql/save.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/tsql/snippets.gif filter=lfs diff=lfs merge=lfs -text +docs/languages/images/typescript/Languages_typescript.png filter=lfs diff=lfs merge=lfs -text +docs/languages/images/typescript/intellisense.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/typescript/jsdoc-autofill.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/typescript/jsx-tag-complete.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/typescript/organize-imports.mp4 filter=lfs diff=lfs merge=lfs -text +docs/languages/images/typescript/overview.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/emberjs/welcome-page.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/extensions/chrome_debugger.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/extensions/document_this.gif filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/extensions/npm_intellisense.gif filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/nodejs/debugsession.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/nodejs/hello-world-debugging.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/nodejs/runtimes_node.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/nodejs-debugging/auto-attach-cluster.gif filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/nodejs-debugging/auto-attach.gif filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/nodejs-debugging/loaded-scripts-explorer.gif filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/nodejs-debugging/loaded-scripts.gif filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/reactjs/hit-breakpoint.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/recipes/chrome.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/recipes/electron.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/recipes/mern.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/recipes/node-typescript-docker.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/recipes/nodejs.png filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/working-with-javascript/checkjs-example.gif filter=lfs diff=lfs merge=lfs -text +docs/nodejs/images/working-with-javascript/disable-TS-language.png filter=lfs diff=lfs merge=lfs -text +docs/other/images/office/yoofficemanifest.png filter=lfs diff=lfs merge=lfs -text +docs/other/images/unity/wow.gif filter=lfs diff=lfs merge=lfs -text +docs/python/images/debugging/debugGAE.gif filter=lfs diff=lfs merge=lfs -text +docs/python/images/deploy-containers/deploy-to-app-service.gif filter=lfs diff=lfs merge=lfs -text +docs/python/images/editing/python-editing.gif filter=lfs diff=lfs merge=lfs -text +docs/python/images/editing/refactorExtractMethod.gif filter=lfs diff=lfs merge=lfs -text +docs/python/images/jupyter/jupyter-notebook.png filter=lfs diff=lfs merge=lfs -text +docs/setup/images/mac/touchbar.gif filter=lfs diff=lfs merge=lfs -text +docs/setup/images/quicksetup/QuickSetup.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/0_10_0/hello-code.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/0_8_0/colorthemes.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_10/column-breakpoints.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_10/copy-with-syntax-highlighting.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_10/drag-and-drop.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_10/jsdoc-autofill.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_10/launch-keyboard.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_10/minimap-blocks-scroll.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_10/minimap.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_11/abyss-theme.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_11/color-settings.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_11/config-exceptions.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_11/exception-peekui.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_11/keyboard-shortcuts.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_11/loaded-scripts.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_11/panel.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_12/column-breakpoints.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_12/completions-dynamic-sort.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_12/keyboard-shortcuts-editor.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_12/native-tabs.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_12/terminal-line-col-link.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_12/theme-activitybar.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_12/theme-generator.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_12/ts-checkjs-example.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/emmet.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/high-contrast.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/jsx-new-coloring.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/letter-spacing.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/markdown-heading-levels.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/new-setting-defaults.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/resize-find-widget.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/snippets-multi-cursor.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/step-after.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/step-before.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/suggest.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/task-customize.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/terminal-vtop-after.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/terminal-vtop-before.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_13/uncover-matched-results.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/commands-history.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/emmet.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/empty-window-restore.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/github-issues-and-prs.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/gitignore.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/js-refactoring.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/minimap-horizontal-slider.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/quick-switch-windows.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/tasks-matcher-attach.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/terminal-selection-select.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_14/ts-build-task.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_15/folder_settings.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_15/loaded-scripts-explorer.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_15/markdown-preview-search.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_15/markdown-security.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_15/react-tutorial.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_15/snippet-choice.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_15/views_management.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_15/workspace.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_15/workspace_settings.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_16/auto-close1.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_16/eh-breakpoints.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_16/exthost-restart.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_16/folder-drop.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_16/multi-root-dnd.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_16/multi-root-transition.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_16/scm-multiroot.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_16/search-dnd.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_16/smooth-scrolling.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_16/ts-extract.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_17/console_messages.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_17/js-markdown-intellisense.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_17/markdown-fenced-commenting.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_17/offside-folding.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_17/quick-suggestion-path-intellisense.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_17/region-folding.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_17/scm.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_17/terminal_60fps.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_17/touchbar.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_17/wait.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_18/diff.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_18/git-decorations.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_18/merge.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_18/multiroot.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_18/panel-title.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_18/recommendationinstall-configure.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_18/recommendations-badge.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_18/string-quick-suggestions.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_18/ts-extract-local.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_18/vertical-panel.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_19/image-diff.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_19/shrink.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_19/status.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_19/stdin.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_19/suggest_mem.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_19/vscode-processes.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/auto-attach-cluster.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/emmetprefix.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/filerec.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/git-input-validation.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/image-zoom.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/minimap-left-side.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/multi-select.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/output-log-channels.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/popular-extension.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/save_admin.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/submodules.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/tab_hover.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/toggle-ignore-trim-whitespace.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_20/ts-auto-import-default.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/centeredLayout.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/emmet-style.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/manage-builtin.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/md-dynamic-preview.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/md-scroll-sync.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/notifications.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/path-completion.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/search.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/terminal-split.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/window-copy-paste.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_21/window-dnd-files.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/auto-attach.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/f8-navigation.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/log-points.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/markdown-folding.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/references-f4.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/related-diagnostics-information.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/save_part.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/syntax-fold.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/syntaxhighlight-optimization.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/terminal-command-tracking.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/ts-jsdocs-quicksuggestions.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/ts-organize-imports.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_22/wrap.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/SublimeSettingsImporter.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/active-indent-guide.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/copy-search.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/css-csstree.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/css-folding.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/css-mdn.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/editor-column-select.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/editor-stability.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/fsp.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/logpoints.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/markdown-restore.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/problems_filter.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/process-explorer.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_23/webview.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_24/debug_toolbar.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_24/grid.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_24/inline-diff-syntax.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_24/outline-all.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_24/scss-at.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_24/settings-editor.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_24/ts-import-folding.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_24/ts-move-to-file-post.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_24/ts-move-to-file-pre.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_24/ts-update-imports.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/debugtoolbar.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/defaultExtensionsView.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/drop.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/editor-sub-word-navigation.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/editorPaneBackground.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/grid-dnd.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/grid-layout.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/lsp-inspector.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/multistepinput.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/settings-editor.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_25/snippet_placeholder_transform.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/breadcrumbs_active.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/breadcrumbs_tabs_notabs.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/extension-intellisense.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/grid-maximize.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/multistepinput.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/open-folder-uri.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/quickfix-problems.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/rapid_render.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/settings-editor.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/terminal-column-selection.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/ts-convert-to-namespace-import.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/ts-import-all-quick-fix.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/ts-jsx-folding.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/ts-jsx-tag-complete.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_26/webview-icon.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_27/css-definition.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_27/css-import.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_27/extension-settings.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_27/github_pull_requests.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_27/log-streaming.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_27/picker-highlights.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_27/search-filter.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_28/comment_edit.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_28/deleted.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_28/markdown-folding.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_28/markdown-preview-link.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_28/record-keybindings.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_28/tabcompletion.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_28/ts-convert-to-async.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_28/ts-rename-import.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_29/file-icon-preview.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_29/highlight-modified-tabs.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_29/json-schema-loading.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_29/mojave-dark.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_29/multiline.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_29/references-view.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_29/workbench-navigation.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/api-sighelp-context.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/custom-title-menu-linux.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/debug-from-process-explorer.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/downgrade-Extension.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/exthost-slow-the-movie.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/go-to-declaration.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/html-custom-tag-attribute.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/input-example.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/references-viewlet.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/settings-actions.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/ts-new-callback-nav.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/ts-new-quickfix.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/ts-old-callback-nav.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_30/ts-rename.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/api-toc.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/customdata.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/html-css-json-selection.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/live-theme-editing.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/no-reload-language-extension.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/problems-multi-line.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/ref-history.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/screencast.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/select-all.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/smart-select-demo.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/terminal-cwd-links.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/terminal-reflow.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_31/type-filter.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_32/column-selection-alt-key.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_32/debug-console-font.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_32/html-attribute-completion.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_32/keyboard-shortcuts-when.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_32/problem-hover.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_32/server-ready.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_32/theme-install.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_32/vetur-intellisense-vue-template.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_7/hitCount.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_7/horizontal.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_7/multiDebug.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_8/add-config.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_8/hide-activitybar.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_8/javascript-in-html.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_8/quick-edit-settings.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_8/search-settings.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_8/viewlet.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/configure-lang-mode.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/inline_values.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/log-objects.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/markdown-double-click-preview-switch.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/markdown-preview-to-editor-scroll-sync.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/markdown-selection-preview-scroll-sync.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/no_folder_debug.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/search-result-nav.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/settings.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/tasks.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/terminal-after.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/1_9/toggle-skip-file.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/April/smartStepping.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/February/function-breakpoint.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/February/high-contrast.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/January/api-virtual-documents.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/July_2016/insertSnippet.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/July_2016/restartFrame.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/July_2016/tabCompletion.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/June_2016/dnd_editor.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/June_2016/editor-mouse-wheel-zoom.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/June_2016/extensions_viewlet.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/June_2016/multiline-find.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/June_2016/searchAndReplace.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/June_2016/social.jpg filter=lfs diff=lfs merge=lfs -text +release-notes/images/June_2016/stacks.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/June_2016/tabs.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/March/column-select-mouse.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/March/extension-widget.png filter=lfs diff=lfs merge=lfs -text +release-notes/images/May_2016/peek.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/May_2016/selectAllFindMatches.gif filter=lfs diff=lfs merge=lfs -text +release-notes/images/May_2016/tabsprogress.png filter=lfs diff=lfs merge=lfs -text +tutorials/images/docker-extension/create.gif filter=lfs diff=lfs merge=lfs -text +tutorials/images/functions-extension/function-debugging.png filter=lfs diff=lfs merge=lfs -text +tutorials/images/functions-extension/functions-vscode-intro.png filter=lfs diff=lfs merge=lfs -text +tutorials/images/nodejs-deployment/emptyazuresite.png filter=lfs diff=lfs merge=lfs -text +tutorials/images/nodejs-deployment/searchforextension.png filter=lfs diff=lfs merge=lfs -text +tutorials/images/nodejs-deployment/sqlextension.png filter=lfs diff=lfs merge=lfs -text +tutorials/images/static-website/azure-app.png filter=lfs diff=lfs merge=lfs -text +tutorials/images/static-website/updated-azure-app.png filter=lfs diff=lfs merge=lfs -text diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..e2ecc17bff559d5f8c931ebf477781aa5ca7bf1c --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +_build +node_modules + +.DS_Store +.vscode/spell.json + +.idea + +*.sublime-project +*.sublime-workspace \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000000000000000000000000000000000000..c96a3db8f6004abf4f218f6c5a4b68a641a853d4 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,9 @@ +// Place your settings in this file to overwrite default and user settings. +{ + "editor.wordWrap": "on", + "files.eol": "\n", + "files.trimTrailingWhitespace": true, + "files.associations": { + "**/toc.json": "jsonc" + } +} \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..9de998e01904b44f01a7e080d9302302d3159ccd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,188 @@ +# Visual Studio Code Documentation + +You've found the GitHub repository that houses the source for the VS Code docs at . + +## Contribute to VS Code documentation + +Thank you for your interest in VS Code documentation! + +* [Contributing](#contributing) +* [Documentation intent](#documentation-intent) +* [Repository organization](#repository-organization) +* [Branches](#branches) +* [Authoring Tools](#authoring-tools) +* [How to use Markdown to format your topic](#how-to-use-markdown-to-format-your-topic) +* [Topic Metadata](#topic-metadata) +* [Formatting](#formatting) + +>**Note**: Before submitting a pull request, especially for rendering or link issues, please review the content on the official VS Code website, [code.visualstudio.com](https://code.visualstudio.com). The element in question may render correctly after processing by the website build. + +## Contributing + +To contribute to [VS Code documentation](https://code.visualstudio.com/docs), you need to fork this repository and submit a pull request for the Markdown and/or image changes that you're proposing. + +* [How to fork a repository](https://help.github.com/articles/fork-a-repo) +* [How to make a pull request](https://help.github.com/articles/creating-a-pull-request/) +* [Changing a commit message](https://help.github.com/articles/changing-a-commit-message/) +* [How to squash commits](https://help.github.com/articles/about-pull-request-merges/) + +## Documentation intent + +The goal of the VS Code documentation is to educate users on VS Code features and how VS Code can be used to enhance their development experience with different programming languages and runtimes. + +The documentation is not intended to provide: + +* An introduction to coding or software development +* Tutorials on technologies independent from VS Code +* Promotion of third-party tools, plug-ins or services +* Excessive detail or advanced walkthroughs + +The documentation should target developers learning to use VS Code or searching for quick answers to commonly asked questions. Other forums such as blog posts can provide more detailed content elaborating on specific scenarios. + +## Repository organization + +The content in this repository follows the organization of documentation at . + +This repository contains the following folders: + +* \setup +* \introvideos +* \getstarted +* \editor +* \languages +* \extensions +* \extensionAPI +* \other +* \supporting + +Within these folders you'll find the Markdown files used for the content. Each of these folders also contains an \images folder that references the images (such as screenshots) used in the topics. + +### Branches + +We recommend that you create local working branches that target a specific scope of change (and then submit a pull request when your changes are ready). Each branch should be limited to a single concept/topic, both to streamline work flow, and to reduce the possibility of merge conflicts. The following efforts are of the appropriate scope for a new branch: + +* A new topic (and associated images). +* Spelling and grammar edits on a topic. +* Applying a single formatting change across a large set of topics. + +## Authoring tools + +[Visual Studio Code](https://code.visualstudio.com) is a great editor for Markdown! + +In fact, VS Code and its core documentation are written using VS Code. + +## How to use Markdown to format your topic + +The topics in this repository use Markdown. Here is a good overview of [Markdown basics](https://help.github.com/articles/markdown-basics/). + +## Topic Metadata + +Topic metadata enables certain functionalities for the topics such as table of contents order, topic descriptions, and online search optimization as well as aiding Microsoft in evaluating the effectiveness of the content. + +* **Order** - This is the order that is used in the left rail TOC, the page is left out of the TOC if this is blank +* **Area** - General area within VS Code +* **TOCTitle** - The title used in the left rail Table of Contents for this page +* **PageTitle** - The title used in the HTML title for the page and in search results +* **ContentId** - A GUID which uniquely identifies the topic to DevDiv doc reporting. +* **DateApproved** - This is set when the page is actually published on the VS Code portal. You can ignore it. +* **MetaDescription** - The meta description for this page which helps for search. Use sentence structure limited to 300 characters. +* **MetaSocialImage** - Optional. Used for og:image in page header for sharing on social media. Should be 1024 x 512 .png. +* **MetaTags** - Optional. Further tags for this page again for search. + +## Product name + +Use the full product name "Visual Studio Code" in the topic MetaDescription and the first use in a topic. You can use the shortened "VS Code" after that throughout the rest of the content. Do not use "VSCode" (no space) or "Code". + +### Metadata for /api docs + +**For Writer**: + +* **MetaDescription** - The meta description for this page which helps for search + +**For Doc Maintainer**: + +* **DateApproved** - This is set when the page is actually published on the VS Code portal. + +## Formatting + +### Headings & Right Nav + +H2 subheadings `##` end up in the right hand jump list for the document (this happens in our compile script). It's a good idea to include h2 subheadings to help users get an overview of the doc and quickly navigate to the major topics. + +### Text formatting + +Use bold for VS Code commands and UI elements. + + **Extensions: Install Extension** + **Debug Console** + +Limit the use of bold for emphasis unless it is crucial to get the user's attention. Avoid the use of italics for emphasis since italics doesn't render well on the code.visualstudio.com site. + +Use inline code formatting (backticks) for settings, filename and JSON attributes. + + `files.exclude` + `tasks.json` + `preLaunchTask` + +Use '>' to show menu sequence. + + **File** > **Preferences** > **Settings** + **View** > **Command Palette** + +### Links + +For links within our own documentation, use a site relative link like `/docs/editor/codebasics.md`. + +>For example: `[Why VS Code](/docs/editor/whyvscode.md)` - links to the **Why Visual Studio Code** page + +>**Correction:** For this repo to ease content development you should add the .md suffix. We will parse these out for the website deployment. + +### Bookmarks + +To provide links to h2 subheadings (Markdown ##), the format is `[Link Text](page.md#subheading-title)`. + +Note the subheading title is lowercase and subheading title words are separated by '-' hyphens. + +>For example: `[Keyboard Shortcuts](/docs/editor/codebasics.md#keyboard-shortcuts)` - links to https://code.visualstudio.com/docs/editor/codebasics#_keyboard-shortcuts. + +### Images + +Images are important to bring the product to life - even if people can't try the product, these really help them to see what they are missing. + +For images you're adding to the repo, store them in the `images` subfolder of the TOC section, for example: `editor\images\debugging`. + +When you link to an image, the path and filename are case-sensitive. The convention is for image filenames to be all lowercase. + +>For example: `![Debug Breakpoints](images/debugging/breakpoints.png)` + +### Key bindings + +The VS Code portal is able to show the correct key bindings depending on the reader's operating system (macOS, Windows or Linux). + +To enable this for keyboard shortcuts, use the format `kb(workbench.action.files.openFile)` where the command name is included in parentheses. + +>For a list of key bindings and the relevant `Command Ids` review the [key bindings document](https://code.visualstudio.com/docs/getstarted/keybindings). + +If you are listing out multiple key bindings, you can use a table. + +>Shortcut|Key Strokes +>--------|----------- +>Cut|`kb(editor.action.clipboardCutAction)` +>Copy|`kb(editor.action.clipboardCopyAction)` +>Paste|`kb(editor.action.clipboardPasteAction)` + +### Source Code + +For source code we use the fenced code block notation ```` ``` ````. + +>**Note:** You can add an optional language identifier to enable syntax highlighting in your fenced code block. E.g. ```` ```json ```` or ```` ```javascript ````. [Read more →](https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting) + +Some JavaScript code... + +```javascript +function fancyAlert(arg) { + if (arg) { + $.facebox({ div: foo }); + } +} +``` diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000000000000000000000000000000000000..8779195d3f95a3d191b7e2674b82191544de231b --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,6 @@ +Copyright (c) Microsoft Corporation. All rights reserved. Distributed under the following terms: + +1. Documentation is licensed under the [Creative Commons Attribution 3.0 United States License](https://creativecommons.org/licenses/by/3.0/us/legalcode). Code is licensed under the [MIT License](https://opensource.org/licenses/MIT). + +2. This license does not grant you rights to use any trademarks or logos of Microsoft. For Microsoft’s general trademark guidelines, go to https://go.microsoft.com/fwlink/?LinkID=254653. + diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..1714e3da3fe94620b3ecff072eae46dc37b808e0 --- /dev/null +++ b/README.md @@ -0,0 +1,66 @@ +
+vscode logo +
+ +# Visual Studio Code Documentation + +You've found the Visual Studio Code documentation GitHub repository, which contains the content for the [Visual Studio Code documentation](https://code.visualstudio.com/docs). + +Topics submitted here will be published to the [Visual Studio Code](https://code.visualstudio.com) portal. + +If you are looking for the VS Code product GitHub repository, you can find it [here](https://github.com/Microsoft/vscode). + +## Index +1. [About Visual Studio Code](#visual-studio-code) +2. [Contributing to the documentation](#contributing-to-the-documentation) +3. [Feedback](#feedback) +4. [Documentation Issues](#documentation-issues) +5. [Editing](#editing) +6. [Publishing](#publishing) + +## Visual Studio Code + +[VS Code](https://code.visualstudio.com/) is a lightweight source code editor and powerful development environment for building and debugging modern web and cloud applications. It is free and available on your favorite platform - Linux, macOS, and Windows. + +If you landed here looking for other information about VS Code, head over to [our website](https://code.visualstudio.com) for additional information. + +## Contributing to the documentation + +To contribute with new topics/information or make changes to existing documentation, see [contributing](https://github.com/Microsoft/vscode-docs/blob/master/CONTRIBUTING.md#contributing) for instructions and guidelines. + +## Feedback + +If you want to give documentation feedback, please use the feedback control located at the bottom of each documentation page. + +## Documentation Issues + +To enter documentation bugs, please create a [new GitHub issue](https://github.com/Microsoft/vscode-docs/issues) (try to check if there isn't a topic about your issue already). + +If you think the issue is with the VS Code product itself, please enter issues [here](https://github.com/Microsoft/vscode/issues). + +## Editing + +In order to edit the VS Code documentation, ensure that you have [Git](https://git-scm.com/downloads) installed. + +Clone a copy of the repo: + +``` +git clone https://github.com/Microsoft/vscode-docs.git +``` + +VS Code itself is great for reviewing and editing [Markdown](https://code.visualstudio.com/docs/languages/markdown) with nice preview support. + +If you want to use VS Code, simply navigate to the `vscode-docs` directory and launch VS Code from there: + +``` +cd vscode-docs +code . +``` + +You can open any of the Markdown files and see a preview with the **Open Preview to the Side** button in the upper right of the editor. + +![Markdown Preview Button](images/MDPreviewButton.png) + +## Publishing + +Steps for how to publish documentation changes can be found [here](https://github.com/Microsoft/vscode-website#publishing-a-documentation-change) in the (private) repository of the VS Code website. diff --git a/api/.prettierrc.json b/api/.prettierrc.json new file mode 100644 index 0000000000000000000000000000000000000000..52f9dcba6ba2014f0989b4c1eb6d842657fabee5 --- /dev/null +++ b/api/.prettierrc.json @@ -0,0 +1,5 @@ +{ + "printWidth": 92, + "tabWidth": 2, + "singleQuote": true +} \ No newline at end of file diff --git a/api/advanced-topics/extension-host.md b/api/advanced-topics/extension-host.md new file mode 100644 index 0000000000000000000000000000000000000000..aa2f6175b0d4631212a6d6ed28a5154a9c3c0a9a --- /dev/null +++ b/api/advanced-topics/extension-host.md @@ -0,0 +1,24 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 106AA11C-DB26-493A-9E3C-16F513B2AEC8 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: The Visual Studio Code Extension Host is responsible for managing extensions and ensuring the stability and performance of Visual Studio Code. +--- + +# Extension Host + +As you learned in the [Extension Anatomy](/api/get-started/extension-anatomy) topic, an extension exposes the `activate` and `deactivate` methods and VS Code will manage its lifecycle. This topic provides more details on the **Extension Host** that manages all running extensions. + +**Extension host** is a Node.js process in VS Code responsible for loading and running extensions. Although you don't need to worry about the Extension Host when you are writing extensions, it is still useful to know what the Extension Host does to your extension. + +## Stability and Performance + +VS Code aims to deliver a stable and performant editor to end users, and misbehaving extensions should not impact the user experience. The Extension Host in VS Code prevents extensions from: + +- Impacting startup performance +- Slowing down UI operations +- Modifying the UI + +Additionally, VS Code lets extensions declare its [Activation Events](/api/references/activation-events) and loads them lazily. For example, the Markdown extension should only be loaded when a user opens a Markdown file. This makes sure that extensions do not consume unnecessary CPU and memory. diff --git a/api/advanced-topics/using-proposed-api.md b/api/advanced-topics/using-proposed-api.md new file mode 100644 index 0000000000000000000000000000000000000000..6c9ac81154602f2e71e3e3939dda1b6c7d93e0a2 --- /dev/null +++ b/api/advanced-topics/using-proposed-api.md @@ -0,0 +1,22 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: f4d4e9e0-8901-405c-aaf5-faa16c32588b +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Use Visual Studio Code's Proposed API +--- + +# Using Proposed API + +At Visual Studio Code, we take Extension API compatibility seriously. We give our best effort to avoid breaking API changes, and extension authors could expect published extensions to continue to work. However, this puts great limitation on us: once we introduce an API, we cannot easily change it any more. + +Proposed API solves the problem for us. Proposed API is a set of unstable API that are implemented in VS Code but not exposed to the public as stable API does. They are **subject to change**, **only available in Insider distribution** and **cannot be used in published extensions**. Nevertheless, extension authors could test these new API in local development and provide feedback for VS Code team to iterate on the API. Eventually, Proposed API finds their way into the stable API and becomes available for general use. + +## Using Proposed API + +These are the steps for testing Proposed API in local extension development: + +- Use [Insiders](/insiders) release of VS Code. +- Add `"enableProposedApi": true` to your `package.json`. +- Copy the latest version of the [`vscode.proposed.d.ts`](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.proposed.d.ts) into your project. diff --git a/api/extension-capabilities/common-capabilities.md b/api/extension-capabilities/common-capabilities.md new file mode 100644 index 0000000000000000000000000000000000000000..abcf7c08751d31944d06a9323c12ad7b05d65acf --- /dev/null +++ b/api/extension-capabilities/common-capabilities.md @@ -0,0 +1,78 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 9c48dfbf-e49d-4f33-aadc-5ebf06d5dde0 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Common capabilities that Visual Studio Code extensions (plug-ins) can take advantage of +--- + +# Common Capabilities + +Common Capabilities are important building blocks for your extensions. Almost all extensions use some of these functionalities. Here is how you can take advantage of them. + +## Command + +Command is central to how VS Code works. You open the Command Palette to execute commands, bind custom keybindings to commands, and right-click to invoke commands in Context Menus. + +An extension could: + +- Register and execute commands with the [`vscode.commands`](/api/references/vscode-api#commands) API. +- Make commands available in the Command Palette with the [`contributes.commands`](/api/references/contribution-points#contributes.commands) Contribution Point. + +Learn more about commands at the [Extension Guides / Command](/api/extension-guides/command) topic. + +## Configuration + +An extension can contribute extension-specific settings with the [`contributes.configuration`](/api/references/contribution-points#contributes.configuration) Contribution Point and read them using the [`workspace.getConfiguration`](/api/references/vscode-api#workspace.getConfiguration) API. + +## Keybinding + +An extension can add custom keybindings. Read more in the [`contributes.keybindings`](/api/references/contribution-points#contributes.keybindings) and [Key Bindings](/docs/getstarted/keybindings) topics. + +## Context Menu + +An extension can register custom Context Menu items that will be displayed in different parts of the VS Code UI on right-click. Read more at the [`contributes.menus`](/api/references/contribution-points#contributes.menus) Contribution Point. + +## Data Storage + +There are three options for storing data: + +- [`ExtensionContext.workspaceState`](/api/references/vscode-api#ExtensionContext.workspaceState): A workspace storage where you can write key/value pairs. VS Code manages the storage and will restore it when the same workspace is opened again. +- [`ExtensionContext.globalState`](/api/references/vscode-api#ExtensionContext.globalState): A global storage where you can write key/value pairs. VS Code manages the storage and will restore it for each extension activation. +- [`ExtensionContext.storagePath`](/api/references/vscode-api#ExtensionContext.storagePath): A workspace specific storage path pointing to a local directory where your extension has write/read access. This is a good option if you need to store large files that is accessible only from current workspace. +- [`ExtensionContext.globalStoragePath`](/api/references/vscode-api#ExtensionContext.globalStoragePath): A global storage path pointing to a local directory where your extension has write/read access. This is a good option if you need to store large files that is accessible from all workspaces. + +The extension context is available to the `activate` function in the [Extension Entry File](/api/get-started/extension-anatomy#extension-entry-file). + +## Display Notifications + +Almost all extensions need to present information to the user at some point. VS Code offers three APIs for displaying notification messages of different severity: + +- [`window.showInformationMessage`](/api/references/vscode-api#window.showInformationMessage) +- [`window.showWarningMessage`](/api/references/vscode-api#window.showWarningMessage) +- [`window.showErrorMessage`](/api/references/vscode-api#window.showErrorMessage) + +## Quick Pick + +With the [`vscode.QuickPick`](/api/references/vscode-api#QuickPick) API, you can easily collect user input or let the user make a selection from multiple options. The [QuickInput Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/quickinput-sample) illustrates the API. + +## File Picker + +Extensions can use the [`vscode.window.showOpenDialog`](/api/references/vscode-api#vscode.window.showOpenDialog) API to open the system file picker and select files or folders. + +## Output Channel + +The Output Panel displays a collection of [`OutputChannel`](/api/references/vscode-api#OutputChannel), which are great for logging purpose. You can easily take advantage of it with the [`window.createOutputChannel`](/api/references/vscode-api#window.createOutputChannel) API. + +## Progress API + +You can use the [`vscode.Progress`](/api/references/vscode-api#Progress) API for reporting progress updates to the user. + +Progress can be shown in different locations using the [`ProgressLocation`](/api/references/vscode-api#ProgressLocation) option: + +- In the Notifications area +- In the Source Control view +- General progress in the VS Code window + +The [Progress Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/progress-sample) illustrates this API. diff --git a/api/extension-capabilities/extending-core-functionalities.md b/api/extension-capabilities/extending-core-functionalities.md new file mode 100644 index 0000000000000000000000000000000000000000..06dc0615cc54c0e6d6c4d41bac5eebee90816ca9 --- /dev/null +++ b/api/extension-capabilities/extending-core-functionalities.md @@ -0,0 +1,12 @@ +--- +DateApproved: +MetaDescription: +--- + +# Extending Core Functionalities + +Talk about the core functionalities that extension could plug-in their providers for: + +- File System Provider +- Search Provider +- SCM Provider diff --git a/api/extension-capabilities/extending-workbench.md b/api/extension-capabilities/extending-workbench.md new file mode 100644 index 0000000000000000000000000000000000000000..2c46f815db359ea1600cbfb9cbfb10e52babd006 --- /dev/null +++ b/api/extension-capabilities/extending-workbench.md @@ -0,0 +1,49 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: e0d5bd37-f020-4235-ad81-c977baaeb24f +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Explain how to extend Visual Studio Code's workbench area with custom UI components +--- + +# Extending Workbench + +"Workbench" refers to the overall Visual Studio Code UI that encompasses the following UI components: + +- Title Bar +- Activity Bar +- Side Bar +- Panel +- Editor Group +- Status Bar + +VS Code provides various APIs that allow you to add your own components to the Workbench. For example, in the image below: + +![workbench-contribution](images/extending-workbench/workbench-contribution.png) + +- Activity Bar: The [Azure App Service extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) adds a [View Container](#view-container) +- Side Bar: The built-in [NPM extension](https://github.com/Microsoft/vscode/tree/master/extensions/npm) adds a [Tree View](#tree-view) to the Explorer View +- Editor Group: The built-in [Markdown extension](https://github.com/Microsoft/vscode/tree/master/extensions/markdown-language-features) adds a [Webview](#webview) next to other editors in the Editor Group +- Status Bar: The [VSCodeVim extension](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) adds a [Status Bar Item](#status-bar-item) in the Status Bar + +## Views Container + +With the [`contributes.viewsContainers`](/api/references/contribution-points#contributes.viewsContainers) Contribution Point, you can add new Views Containers that display next to the five built-in Views Containers. Learn more at the [Tree View](/api/extension-guides/tree-view) topic. + +## Tree View + +With the [`contributes.views`](/api/references/contribution-points#contributes.views) Contribution Point, you can add new Views that display in any of the View Containers. Learn more at the [Tree View](/api/extension-guides/tree-view) topic. + +## Webview + +Webviews are highly customizable views built with HTML/CSS/JavaScript. They display next to text editors in the Editor Group areas. Read more about Webview in the [Webview Guide](/api/extension-guides/webview). + +## Status Bar Item + +Extensions can create custom [`StatusBarItem`](/api/references/vscode-api#StatusBarItem) that display in the Status Bar. Status Bar Items can show text and icons and run commands on click events. + +- Show text and icons +- Run a command on click + +A Status Bar extension sample can be found [here](https://github.com/Microsoft/vscode-extension-samples/tree/master/statusbar-sample). diff --git a/api/extension-capabilities/images/extending-workbench/workbench-contribution.png b/api/extension-capabilities/images/extending-workbench/workbench-contribution.png new file mode 100644 index 0000000000000000000000000000000000000000..37867c91e2445ab2c07242f09576010e2ec266ae --- /dev/null +++ b/api/extension-capabilities/images/extending-workbench/workbench-contribution.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5776da85f8813b18ade37dc4ceece172001ee5a5308d20caa05b437450ccb787 +size 417626 diff --git a/api/extension-capabilities/images/theming/color-theme.png b/api/extension-capabilities/images/theming/color-theme.png new file mode 100644 index 0000000000000000000000000000000000000000..60da06167254466c7b4a43b60555cac0d515c598 --- /dev/null +++ b/api/extension-capabilities/images/theming/color-theme.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:150f31aeda53cfe4eb832a69457f3258fdd5f262d286db5b5acaeb1610a356f6 +size 275820 diff --git a/api/extension-capabilities/images/theming/icon-theme.png b/api/extension-capabilities/images/theming/icon-theme.png new file mode 100644 index 0000000000000000000000000000000000000000..5e5bc965d7d66c6e53b00268f817b24b0e4619ff --- /dev/null +++ b/api/extension-capabilities/images/theming/icon-theme.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f791379a21d1276af0571483da9235ec0fd79aa33b8eef5d75b69bc3000bb8ed +size 664370 diff --git a/api/extension-capabilities/overview.md b/api/extension-capabilities/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..26a7a1dce549de01ed5a9ca23943b7539787d2ee --- /dev/null +++ b/api/extension-capabilities/overview.md @@ -0,0 +1,121 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: d22675fc-6609-43f2-a66b-8f2a52597195 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Learn the details of what's possible with Visual Studio Code's rich extension (plug-in) API. +--- + +# Extensions Capabilities Overview + +Visual Studio Code offers many ways for extensions to extend its capabilities. It can sometimes be hard to find the right [Contribution Points](/api/references/contribution-points) and [VS Code API](/api/references/vscode-api) to use. This topic splits extension capabilities into a few categories. Each category describes: + +- Some functionalities your extension could use +- Links to more detailed topics for using these functionalities +- A few extension ideas + +However, we also impose [restrictions](#restrictions) upon extensions to ensure the stability and performance of VS Code. For example, extensions cannot access the DOM of VS Code UI. + +## Common Capabilities + +[Common Capabilities](./common-capabilities) are core pieces of functionality that you can use in any extension. + +Some of these capabilities include: + +- Registering commands, configurations, keybindings, or context menu items. +- Storing workspace or global data. +- Displaying notification messages. +- Using Quick Pick to collect user input. +- Open the system file picker to let users select files or folders. +- Use the Progress API to indicate long-running operations. + +## Theming + +[Theming](./theming) controls the look of VS Code, both the colors of source code in the editor and the colors of the VS Code UI. If you've ever wanted to make it look like you're coding the Matrix by making VS Code different shades of green, or just wanted to create the ultimate, minimalist grayscale workspace, then themes are for you. + +**Extension Ideas** + +- Change colors of your source code. +- Change colors of the VS Code UI. +- Port an existing TextMate theme to VS Code. +- Add custom file icons. + +## Declarative Language Features + +[Declarative Language Features](/api/language-extensions/overview#declarative-language-features) adds basic text editing support for a programming language such as bracket matching, auto-indentation and syntax highlighting. This is done declaratively, without writing any code. For more advanced language features, like IntelliSense or debugging, see [Programmatic Language Features](#programmatic-language-features). + +**Extension Ideas** + +- Bundle common JavaScript snippets into an extension. +- Tell VS Code about a new programming language. +- Add or replace the grammar for a programming language. +- Extend an existing grammar with grammar injections. +- Port an existing TextMate grammar to VS Code. + +## Programmatic Language Features + +[Programmatic Language Features](/api/language-extensions/overview#programmatic-language-features) add rich programming language support such as Hovers, Go to Definition, diagnostic errors, IntelliSense and CodeLens. These language features are exposed through the [`vscode.languages.*`](/api/references/vscode-api#languages) API. An extension can either use these API directly, or write a Language Server and adapt it to VS Code using the VS Code [Language Server library](https://github.com/Microsoft/vscode-languageserver-node). + +Although we provide a listing of [language features](/api/language-extensions/programmatic-language-features) and their intended usage, nothing prevents you from using these API creatively. For example, CodeLens and Hovers are a great way to present additional information inline, while diagnostic errors can be used to highlight spelling or code style errors. + +**Extension Ideas** + +- Add hovers that show sample usage of an API. +- Report spelling or linter errors in source code using diagnostics. +- Register a new code formatter for HTML. +- Provide rich, context-aware IntelliSense. +- Add folding, breadcrumbs and outline support for a language. + +## Workbench Extensions + +[Workbench Extensions](./extending-workbench) extend the VS Code Workbench UI. Add new right-click actions to the File Explorer, or even build a custom explorer using VS Code's [TreeView](/api/extension-guides/tree-view) API. And if your extension needs a fully customized user interface, use the [Webview API](/api/extension-guides/webview) to build your own document preview or UI using standard HTML, CSS, and JavaScript. + +**Extension Ideas** + +- Add custom context menu actions to the File Explorer. +- Create a new, interactive TreeView in the Side Bar. +- Define a new Activity Bar view. +- Show new information in the Status Bar. +- Render custom content using the `WebView` API. +- Contribute Source Control providers. + +## Debugging + +You can take advantage of VS Code's [Debugging](/docs/editor/debugging) functionality by writing [Debugger Extensions](/api/extension-guides/debugger-extension) that connect VS Code's debugging UI to a specific debugger or runtime. + +**Extension Ideas** + +- Connect VS Code's debugging UI to a debugger or runtime by contributing a [Debug Adapter implementation](https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/). +- Specify the languages supported by a debugger extension. +- Provide rich IntelliSense and hover information for the debug configuration attributes used by the debugger. +- Provide debug configuration snippets. + +On the other hand, VS Code also offers a set of [Debug Extension API](/api/references/vscode-api#debug), with which you can implement debug-related functionality on top of any VS Code debugger, in order to automate users' debugging experience. + +**Extension Ideas** + +- Start debug sessions based on dynamically created debug configurations. +- Track the lifecycle of debug sessions. +- Create and manage breakpoints programmatically. + + + + +## Restrictions + +There are certain restrictions we impose upon extensions. Here are the restrictions and their purposes. + +### No DOM Access + +Extensions have no access to the DOM of VS Code UI. You **cannot** write an extension that applies custom CSS to VS Code or adds a HTML element to VS Code UI. + +At VS Code, we're continually trying to optimize use of the underlying web technologies to deliver an always available, highly responsive editor and we will continue to tune our use of the DOM as these technologies and our product evolve. To ensure that extensions cannot interfere with the stability and performance of VS Code, and that we can continue to improve the DOM of VS Code without breaking existing extensions, we run extensions in an [Extension Host](/api/advanced-topics/extension-host) process and prevent direct access to the DOM. diff --git a/api/extension-capabilities/theming.md b/api/extension-capabilities/theming.md new file mode 100644 index 0000000000000000000000000000000000000000..148aa34a3eb1fb80e422ab75438e75b1e5216a3e --- /dev/null +++ b/api/extension-capabilities/theming.md @@ -0,0 +1,37 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 37b6ae0a-d1b5-48b6-9bd4-9b50ef11d573 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Learn how to add custom themes for colors and icons in Visual Studio Code. +--- + +# Theming + +In Visual Studio Code, there are two types of themes: + +- **Color Theme**: A mapping from both UI Component Identifier and Text Token Identifier to colors. Color theme allows you to apply your favorite colors to both VS Code UI Components and the text in the editor. +- **Icon Theme**: A mapping from file type / file name to images. The file icon is displayed across the VS Code UI in places such as File Explorer, Quick Open List, and Editor Tab. + +## Color Theme + +![color-theme](images/theming/color-theme.png) + +As you can see in the illustration, Color Theme defines two mappings: + +- The `colors` mapping that controls colors for UI Components. +- The `tokenColors` mapping that controls colors for each source code token (your source code is broken into tokens by a [grammar](/api/language-extensions/syntax-highlight-guide)). + +We have a [Color Theme Guide](/api/extension-guides/color-theme) and a [Color Theme Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/theme-sample) that illustrates how to create a theme. + +## Icon Theme + +Icon themes allow you to: + +- Create a mapping from unique icon identifiers to images or font icons. +- Associate files to these unique icon identifiers by filenames or file language types. + +The [Icon Theme Guide](/api/extension-guides/icon-theme) discusses how to create an Icon Theme. + +![icon-theme](images/theming/icon-theme.png) diff --git a/api/extension-guides/color-theme.md b/api/extension-guides/color-theme.md new file mode 100644 index 0000000000000000000000000000000000000000..eb5b897586a6044e2f9b3db7205920c9c4fea937 --- /dev/null +++ b/api/extension-guides/color-theme.md @@ -0,0 +1,116 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 113b458a-3692-4ccf-a181-048bd572a120 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: A guide to creating Color Theme in Visual Studio Code +--- + +# Color Theme + +Colors visible in the Visual Studio Code user interface fall in two categories: + +- Workbench colors used in views and editors, from the Activity Bar to the Status Bar. A complete list of all these colors can be found in the [theme color reference](/api/references/theme-color). +- Syntax colors used for source code in the editor. The theming of these colors is different as syntax colorization is based on TextMate grammars and TextMate themes. + +This guide will cover the different ways in which you can create themes. + +## Workbench colors + +The easiest way to create a new workbench color theme is to start with an existing color theme and customize it. First switch to the color theme that you want to modify, then open your [settings](/docs/getstarted/settings) and make changes to the `workbench.colorCustomizations` setting. Changes are applied live to your VS Code instance. + +The following, for example, would change the color of the title bar: + +```json +{ + "workbench.colorCustomizations": { + "titleBar.activeBackground": "#ff0000" + } +} +``` + +A complete list of all themable colors can be found in the [color reference](/api/references/theme-color). + +## Syntax colors + +For syntax highlighting colors, there are two approaches. You just simply reference an existing TextMate theme (`.tmTheme` file) from the community, or you can come up with your own theming rules. The easiest way is to start with an existing theme and customize it, much like in the workbench colors section above. + +First switch to the color theme to customize and use the `editor.tokenColorCustomizations` [settings](/docs/getstarted/settings). Changes are applied live to your VS Code instance and no refreshing or reloading is necessary. + +For example, the following would change the color of comments within the editor: + +```json +{ + "editor.tokenColorCustomizations": { + "comments": "#FF0000" + } +} +``` + +The setting supports a simple model with a set of common token types such as 'comments', 'strings' and 'numbers' available. If you want to color more than that, you need to use TextMate theme rules directly, which are explained in detail in the [Syntax Highlighting Guide](/api/language-extensions/syntax-highlight-guide). + +## Create a new Color Theme + +Once you have tweaked your theme colors using `workbench.colorCustomizations` and `editor.tokenColorCustomizations`, it's time to create the actual theme. + +1. Generate a theme file using the **Developer: Generate Color Theme from Current Settings** command from the **Command Palette** +2. Use VS Code's [Yeoman](http://yeoman.io) extension generator to generate a new theme extension: + + ```bash + npm install -g yo generator-code + yo code + ``` + +3. If you customized a theme as described above, select 'Start fresh'. + + ![yo code theme](./images/color-theme/yocode-colortheme.png) + +4. Copy the theme file generated from your settings to the new extension. + +You can also use an existing TextMate theme by telling the extension generator to import a TextMate theme file (.tmTheme) and package it for use in VS Code. Alternatively, if you have already downloaded the theme, replace the `tokenColors` section with a link to the `.tmTheme` file to use. + +```json +{ + "type": "dark", + "colors": { + "editor.background": "#1e1e1e", + "editor.foreground": "#d4d4d4", + "editorIndentGuide.background": "#404040", + "editorRuler.foreground": "#333333", + "activityBarBadge.background": "#007acc", + "sideBarTitle.foreground": "#bbbbbb" + }, + "tokenColors": "./Diner.tmTheme" +} +``` + +> **Tip:** Give your color definition file the `.color-theme.json` suffix and you will get hovers, code completion, color decorators, and color pickers when editing. + +> **Tip:** [ColorSublime](https://colorsublime.github.io) has hundreds of existing TextMate themes to choose from. Pick a theme you like and copy the Download link to use in the Yeoman generator or into your extension. It will be in a format like `"https://raw.githubusercontent.com/Colorsublime/Colorsublime-Themes/master/themes/(name).tmTheme"` + +## Test a new Color Theme + +To try out the new theme, press F5 to launch an Extension Development Host window. + +There, open the Color Theme picker with **File** > **Preferences** > **Color Theme** and you can see your theme in the drop-down list. Arrow up and down to see a live preview of your theme. + +![select my theme](images/color-theme/mytheme.png) + +Changes to the theme file are applied live in the `Extension Development Host` window. + +## Publishing a Theme to the Extension Marketplace + +If you'd like to share your new theme with the community, you can publish it to the [Extension Marketplace](/docs/editor/extension-gallery). Use the [vsce publishing tool](/api/working-with-extensions/publishing-extension) to package your theme and publish it to the VS Code Marketplace. + +> **Tip:** To make it easy for users to find your theme, include the word "theme" in the extension description and set the `Category` to `Theme` in your `package.json`. + +We also have recommendations on how to make your extension look great on the VS Code Marketplace, see [Marketplace Presentation Tips](/api/references/extension-manifest#marketplace-presentation-tips). + +## Adding a new Color Id + +Color ids can also be contributed by extensions through the [color contribution point](/api/references/contribution-points#contributes.colors). These colors also appear when using code complete in the `workbench.colorCustomizations` settings and the color theme definition file. Users can see what colors an extension defines in the [extension contributions](/docs/editor/extension-gallery#_extension-details) tab. + +## Further reading + +- [CSS Tricks - Creating a VS Code theme](https://css-tricks.com/creating-a-vs-code-theme/) diff --git a/api/extension-guides/command.md b/api/extension-guides/command.md new file mode 100644 index 0000000000000000000000000000000000000000..f22b77503d50ce0616ff0cb112fc1ee816984ebb --- /dev/null +++ b/api/extension-guides/command.md @@ -0,0 +1,201 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 995c7085-5fc0-44e0-a171-30a759c0b7da +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: A guide to using commands programmatically in Visual Studio Code extensions (plug-ins) +--- + +# Commands + +Commands trigger actions in Visual Studio Code. If you have ever [configured a keybinding](/docs/getstarted/keybindings), then you've worked with commands. Commands are also used by extensions to expose functionality to users, bind to actions in VS Code's UI, and implement internal logic. + +## Using Commands + +VS Code includes a large set of [built-in commands](/api/references/commands) that you can use to interact with the editor, control the user interface, or perform background operations. Many extensions also expose their core functionality as commands that users and other extensions can leverage. + +### Programmatically executing a command + +The [`vscode.commands.executeCommand`](/api/references/vscode-api#commands.executeCommand) API programmatically executes a command. This lets you leverage VS Code's built-in functionality, and build on extensions such as VS Code's built-in Git and Markdown extensions. + +The `editor.action.addCommentLine` command, for example, comments the currently selected lines in the active text editor: + +```ts +import * as vscode from 'vscode'; + +function commentLine() { + vscode.commands.executeCommand('editor.action.addCommentLine'); +} +``` + +Some commands take arguments that control their behavior. Commands may also return a result. The API-like `vscode.executeDefinitionProvider` command, for example, queries a document for definitions at a given position. It takes a document URI and a position as arguments, and returns a promise with a list of definitions: + +```ts +import * as vscode from 'vscode'; + +async function printDefinitionsForActiveEditor() { + const activeEditor = vscode.window.activeTextEditor; + if (!activeEditor) { + return; + } + + const definitions = await vscode.commands.executeCommand( + 'vscode.executeDefinitionProvider', + activeEditor.document.uri, + activeEditor.selection.active + ); + + for (const definition of definitions) { + console.log(definition); + } +} +``` + +To find available commands: + +- [Browse the keyboard shortcuts](/docs/getstarted/keybindings) +- [Look through VS Code's built-in advanced commands api](/api/references/commands) + +### Command URIs + +Commands URIs are links that execute a given command. They can be used as clickable links in hover text, completion item details, or inside of webviews. + +A command URI uses the `command` scheme followed by the command name. The command URI for the `editor.action.addCommentLine` command, for example, is `command:editor.action.addCommentLine`. Here's a hover provider that shows a link in the comments of the current line in the active text editor: + +```ts +import * as vscode from 'vscode'; + +export function activate(context: vscode.ExtensionContext) { + vscode.languages.registerHoverProvider( + 'javascript', + new class implements vscode.HoverProvider { + provideHover( + _document: vscode.TextDocument, + _position: vscode.Position, + _token: vscode.CancellationToken + ): vscode.ProviderResult { + const commentCommandUri = vscode.Uri.parse(`command:editor.action.addCommentLine`); + const contents = new vscode.MarkdownString(`[Add comment](${commentCommandUri})`); + + // To enable command URIs in Markdown content, you must set the `isTrusted` flag. + // When creating trusted Markdown string, make sure to properly sanitize all the + // input content so that only expected command URIs can be executed + contents.isTrusted = true; + + return new vscode.Hover(contents); + } + }() + ); +} +``` + +The list of arguments to the command is passed as a JSON array that has been properly URI encoded: The example below uses the `git.stage` command to create a hover like that stages the current file: + +```ts +import * as vscode from 'vscode'; + +export function activate(context: vscode.ExtensionContext) { + vscode.languages.registerHoverProvider( + 'javascript', + new class implements vscode.HoverProvider { + provideHover( + document: vscode.TextDocument, + _position: vscode.Position, + _token: vscode.CancellationToken + ): vscode.ProviderResult { + const args = [{ resourceUri: document.uri }]; + const stageCommandUri = vscode.Uri.parse( + `command:git.stage?${encodeURIComponent(JSON.stringify(args))}` + ); + const contents = new vscode.MarkdownString(`[Stage file](${stageCommandUri})`); + contents.isTrusted = true; + return new vscode.Hover(contents); + } + }() + ); +} +``` + +## Creating new commands + +### Registering a command + +[`vscode.commands.registerCommand`](/api/references/vscode-api#commands.registerCommand) binds a command id to a handler function in your extension: + +```ts +import * as vscode from 'vscode'; + +export function activate(context: vscode.ExtensionContext) { + const command = 'myExtension.sayHello'; + + const commandHandler = (name?: string = 'world') => { + console.log(`Hello ${name}!!!`); + }; + + context.subscriptions.push(vscode.commands.registerCommand(command, commandHandler)); +} +``` + +The handler function will be invoked whenever the `myExtension.sayHello` command is executed, be it programmatically with `executeCommand`, from the VS Code UI, or through a keybinding. + +### Creating a user facing command + +`vscode.commands.registerCommand` only binds a command id to a handler function. To expose this command in the Command Palette so it is discoverable by users, you also need a corresponding command `contribution` in your extension's `package.json`: + +```json +{ + "contributes": { + "commands": [ + { + "command": "myExtension.sayHello", + "title": "Say Hello" + } + ] + } +} +``` + +The `commands` contribution tells VS Code that your extension provides a given command, and also lets you control how the command is displayed in the UI. Now our command will show up in the Command Palette: + +![The contributed command in the Command Palette](images/commands/palette.png) + +We still need to call `registerCommand` to actually tie the command id to the handler. This means that if the user selects the `myExtension.sayHello` command from the Command Palette but our extension has not been activated yet, nothing will happen. To prevent this, extensions must register an `onCommand` `activiationEvent` for all user facing commands: + +```json +{ + "activationEvents": ["onCommand:myExtension.sayHello"] +} +``` + +Now when a user first invokes the `myExtension.sayHello` command from the Command Palette or through a keybinding, the extension will be activated and `registerCommand` will bind `myExtension.sayHello` to the proper handler. + +You do not need an `onCommand` activation event for internal commands but you must define them for any commands that: + +- Can be invoked using the Command Palette. +- Can be invoked using a keybinding. +- Can be invoked through the VS Code UI, such as through the editor title bar. +- Is intended as an API for other extensions to consume. + +### Controlling when a command shows up in the Command Palette + +By default, all user facing commands contributed through the `commands` section of the `package.json` show up in the Command Palette. However, many commands are only relevant in certain circumstances, such as when there is an active text editor of a given language or when the user has a certain configuration option set. + +The [`menus.commandPalette`](/api/references/contribution-points#contributes.menus) contribution point lets you restrict when a command should show in the Command Palette. It takes the id of the target command and a [when clause](/docs/getstarted/keybindings#_when-clause-contexts) that controls when the command is shown: + +```json +{ + "contributes": { + "menus": { + "commandPalette": [ + { + "command": "myExtension.sayHello", + "when": "editorLangId == markdown" + } + ] + } + } +} +``` + +Now the `myExtension.sayHello` command will only show up in the Command Palette when the user is in a Markdown file. diff --git a/api/extension-guides/debugger-extension.md b/api/extension-guides/debugger-extension.md new file mode 100644 index 0000000000000000000000000000000000000000..316cd26e24aa49c72e0e4a030ba3bd69a82f07e1 --- /dev/null +++ b/api/extension-guides/debugger-extension.md @@ -0,0 +1,367 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 49EF49AD-8BE6-4D46-ADC8-D678BDC04E85 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Learn how to provide debugger extensions (plug-ins) for Visual Studio Code through a Debug Adapter. +--- + +# Debugger Extension + +Visual Studio Code's debugging architecture allows extension authors to easily integrate existing debuggers into VS Code, while having a common user interface with all of them. + +VS Code ships with one built-in debugger extension, the [Node.js](https://nodejs.org) debugger extension, which is an excellent showcase for the many debugger features supported by VS Code: + +![VS Code Debug Features](images/debugger-extension/debug-features.png) + +This screenshot shows the following debugging features: + +1. Debug configuration management. +2. Debug actions for starting/stopping and stepping. +3. Source-, function-, conditional-, inline breakpoints, and log points. +4. Stack traces, including multi-thread and multi-process support. +5. Navigating through complex data structures in views and hovers. +6. Variable values shown in hovers or inlined in the source. +7. Managing watch expressions. +8. Debug console for interactive evaluation with autocomplete. + +This documentation will help you create a debugger extension which can make any debugger work with VS Code. + +## Debugging Architecture of VS Code + +VS Code implements a generic (language-agnostic) debugger UI based on an abstract protocol that we've introduced to communicate with debugger backends. +Because debuggers typically do not implement this protocol, some intermediary is needed to "adapt" the debugger to the protocol. +This intermediary is typically a standalone process that communicates with the debugger. + +![VS Code Debug Architecture](images/debugger-extension/debug-arch1.png) + +We call this intermediary the **Debug Adapter** (or **DA** for short) and the abstract protocol that is used between the DA and VS Code is the **Debug Adapter Protocol** (**DAP** for short). +Since the Debug Adapter Protocol is independent from VS Code, it has its own [web site](https://microsoft.github.io/debug-adapter-protocol/) where you can find an [introduction and overview](https://microsoft.github.io/debug-adapter-protocol/overview), the detailed [specification](https://microsoft.github.io/debug-adapter-protocol/specification), and some lists with [known implementations and supporting tools](https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/). +The history of and motivation behind DAP is explained in this [blog post](https://code.visualstudio.com/blogs/2018/08/07/debug-adapter-protocol-website#_why-the-need-for-decoupling-with-protocols). + +Since debug adapters are independent from VS Code and can be used in [other developments tools](https://microsoft.github.io/debug-adapter-protocol/implementors/tools/), they do not match VS Code's extensibility architecture which is based on extensions and contribution points. + +For this reason VS Code provides a contribution point, `debuggers`, where a debug adapter can be contributed under a specific debug type (e.g. `node` for the Node.js debugger). VS Code launches the registered DA whenever the user starts a debug session of that type. + +So in its most minimal form, a debugger extension is just a declarative contribution of a debug adapter implementation and the extension is basically a packaging container for the debug adapter without any additional code. + +![VS Code Debug Architecture 2](images/debugger-extension/debug-arch2.png) + +A more realistic debugger extension contributes many or all of the following declarative items to VS Code: + +- List of languages supported by the debugger. VS Code enables the UI to set breakpoints for those languages. +- JSON schema for the debug configuration attributes introduced by the debugger. VS Code uses this schema to verify the configuration in the launch.json editor and provides IntelliSense. +- Default debug configurations for the initial launch.json created by VS Code. +- Debug configuration snippets that a user can add to a launch.json file. +- Declaration of variables that can be used in debug configurations. + +You can find more information in [`contributes.breakpoints`](/api/references/contribution-points#contributes.breakpoints) and [`contributes.debuggers`](/api/references/contribution-points#contributes.debuggers) references. + +In addition to the purely declarative contributions from above, the Debug Extension API enables this code-based functionality: + +- Dynamically generated default debug configurations for the initial launch.json created by VS Code. +- Determine the debug adapter to use dynamically. +- Verify or modify debug configurations before they are passed to the debug adapter. +- Communicate with the debug adapter. +- Send messages to the debug console. + +In the rest of this document we show how to develop a debugger extension. + +## The Mock Debug Extension + +Since creating a debug adapter from scratch is a bit heavy for this tutorial, we will start with a simple DA which we have created as an educational "debug adapter starter kit". It is called _Mock Debug_ because it does not talk to a real debugger, but mocks one. Mock Debug simulates a debugger and supports step, continue, breakpoints, exceptions, and variable access, but it is not connected to any real debugger. + +Before delving into the development setup for mock-debug, let's first install a [pre-built version](https://marketplace.visualstudio.com/items/andreweinand.mock-debug) +from the VS Code Marketplace and play with it: + +- Switch to the Extensions viewlet and type "mock" to search for the Mock Debug extension, +- "Install" and "Reload" the extension. + +To try Mock Debug: + +- Create a new empty folder `mock test` and open it in VS Code. +- Create a file `readme.md` and enter several lines of arbitrary text. +- Switch to the Debug view and press the gear icon. +- VS Code will let you select an "environment" in order to create a default launch configuration. Pick "Mock Debug". +- Press the green Start button and then Enter to confirm the suggested file `readme.md`. + +A debug session starts and you can "step" through the readme file, set and hit breakpoints, and run into exceptions (if the word `exception` appears in a line). + +![Mock Debugger running](images/debugger-extension/mock-debug.gif) + +Before using Mock Debug as a starting point for your own development, we recommend to uninstall the pre-built version first: + +- Switch to the Extensions viewlet and click on the gear icon of the Mock Debug extension. +- Run the "Uninstall" action and then "Reload" the window. + +## Development Setup for Mock Debug + +Now let's get the source for Mock Debug and start development on it within VS Code: + +```bash +git clone https://github.com/Microsoft/vscode-mock-debug.git +cd vscode-mock-debug +npm install +``` + +Open the project folder `vscode-mock-debug` in VS Code. + +What's in the package? + +- `package.json` is the manifest for the mock-debug extension: + - It lists the contributions of the mock-debug extension. + - The `compile` and `watch` scripts are used to transpile the TypeScript source into the `out` folder and watch for subsequent source modifications. + - The dependencies `vscode-debugprotocol`, `vscode-debugadapter`, and `vscode-debugadapter-testsupport` are NPM modules that simplify the development of node-based debug adapters. +- `src/mockRuntime.ts` is a _mock_ runtime with a simple debug API. +- The code that _adapts_ the runtime to the Debug Adapter Protocol lives in `src/mockDebug.ts`. Here you find the handlers for the various requests of the DAP. +- Since the implementation of debugger extension lives in the debug adapter, there is no need to have extension code at all (i.e. code that runs in the extension host process). However, Mock Debug has a small `src/extension.ts` because it illustrates what can be done in the extension code of a debugger extension. + +Now build and launch the Mock Debug extension by selecting the **Extension** launch configuration and hitting `F5`. +Initially, this will do a full transpile of the TypeScript sources into the `out` folder. +After the full build, a _watcher task_ is started that transpiles any changes you make. + +After transpiling the source, a new VS Code window labelled "[Extension Development Host]" appears with the Mock Debug extension now running in debug mode. From that window open your `mock test` project with the `readme.md` file, start a debug session with 'F5', and then step through it: + +![Debugging Extension and Server](images/debugger-extension/debug-mock-session.png) + +Since you are running the extension in debug mode, you could now set and hit breakpoints in `src/extension.ts` but as I've mentioned above, there is not much interesting code executing in the extension. The interesting code runs in the debug adapter which is a separate process. + +In order to debug the debug adapter itself, we have to run it in debug mode. This is most easily achieved by running the debug adapter in _server mode_ and configure VS Code to connect to it. In your VS Code vscode-mock-debug project select the launch configuration **Server** from the drop down menu and press the green start button. + +Since we already had an active debug session for the extension the VS Code debugger UI now enters _multi session_ mode which is indicated by seeing the names of the two debug sessions **Extension** and **Server** showing up in the CALL STACK view: + +![Debugging Extension and Server](images/debugger-extension/debugger-extension-server.png) + +Now we are able to debug both the extension and the DA simultaneously. +A faster way to arrive here is by using the **Extension + Server** launch configuration which launches both sessions automatically. + +An alternative, even simpler approach for debugging the extension and the DA can be found [below](#alternative-approach-to-develop-a-debugger-extension). + +Set a breakpoint at the beginning of method `launchRequest(...)` in file `src/mockDebug.ts` and as a last step configure the mock debugger to connect to the DA server by adding a `debugServer` attribute for port `4711` to your mock test launch config: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "mock", + "request": "launch", + "name": "mock test", + "program": "${workspaceFolder}/readme.md", + "stopOnEntry": true, + "debugServer": 4711 + } + ] +} +``` + +If you now launch this debug configuration, VS Code does not start the mock debug adapter as a separate process, but directly connects to local port 4711 of the already running server, and you should hit the breakpoint in `launchRequest`. + +With this setup, you can now easily edit, transpile, and debug Mock Debug. + +But now the real work begins: you will have to replace the mock implementation of the debug adapter in `src/mockDebug.ts` and `src/mockRuntime.ts` by some code that talks to a "real" debugger or runtime. This involves understanding and implementing the Debug Adapter Protocol. More details +about this can be found [here](https://microsoft.github.io/debug-adapter-protocol/overview#How_it_works). + +## Anatomy of the package.json of a Debugger Extension + +Besides providing a debugger-specific implementation of the debug adapter a debugger extension needs a `package.json` that contributes to the various debug-related contributions points. + +So let's have a closer look at the `package.json` of Mock Debug. + +Like every VS Code extension, the `package.json` declares the fundamental properties **name**, **publisher**, and **version** of the extension. Use the **categories** field to make the extension easier to find in the VS Code Extension Marketplace. + +```json +{ + "name": "mock-debug", + "displayName": "Mock Debug", + "version": "0.24.0", + "publisher": "...", + "description": "Starter extension for developing debug adapters for VS Code.", + "author": { + "name": "...", + "email": "..." + }, + "engines": { + "vscode": "^1.17.0", + "node": "^7.9.0" + }, + "icon": "images/mock-debug-icon.png", + "categories": ["Debuggers"], + + "contributes": { + "breakpoints": [{ "language": "markdown" }], + "debuggers": [ + { + "type": "mock", + "label": "Mock Debug", + + "program": "./out/mockDebug.js", + "runtime": "node", + + "configurationAttributes": { + "launch": { + "required": ["program"], + "properties": { + "program": { + "type": "string", + "description": "Absolute path to a text file.", + "default": "${workspaceFolder}/${command:AskForProgramName}" + }, + "stopOnEntry": { + "type": "boolean", + "description": "Automatically stop after launch.", + "default": true + } + } + } + }, + + "initialConfigurations": [ + { + "type": "mock", + "request": "launch", + "name": "Ask for file name", + "program": "${workspaceFolder}/${command:AskForProgramName}", + "stopOnEntry": true + } + ], + + "configurationSnippets": [ + { + "label": "Mock Debug: Launch", + "description": "A new configuration for launching a mock debug program", + "body": { + "type": "mock", + "request": "launch", + "name": "${2:Launch Program}", + "program": "^\"\\${workspaceFolder}/${1:Program}\"" + } + } + ], + + "variables": { + "AskForProgramName": "extension.mock-debug.getProgramName" + } + } + ] + }, + + "activationEvents": ["onDebug", "onCommand:extension.mock-debug.getProgramName"] +} +``` + +Now take a look at the **contributes** section which contains the contributions specific to debug extensions. + +First, we use the **breakpoints** contribution point to list the languages for which setting breakpoints will be enabled. Without this, it would not be possible to set breakpoints in Markdown files. + +Next is the **debuggers** section. Here, one debugger is introduced under a debug **type** `mock`. The user can reference this type in launch configurations. The optional attribute **label** can be used to give the debug type a nice name when showing it in the UI. + +Since the debug extension uses a debug adapter, a relative path to its code is given as the **program** attribute. +In order to make the extension self-contained the application must live inside the extension folder. By convention, we keep this applications inside a folder named `out` or `bin`, but you are free to use a different name. + +Since VS Code runs on different platforms, we have to make sure that the DA program supports the different platforms as well. For this we have the following options: + +1. If the program is implemented in a platform independent way, e.g. as program that runs on a runtime that is available on all supported platforms, you can specify this runtime via the **runtime** attribute. As of today, VS Code supports `node` and `mono` runtimes. Our Mock debug adapter from above uses this approach. + +1. If your DA implementation needs different executables on different platforms, the **program** attribute can be qualified for specific platforms like this: + + ```json + "debuggers": [{ + "type": "gdb", + "windows": { + "program": "./bin/gdbDebug.exe", + }, + "osx": { + "program": "./bin/gdbDebug.sh", + }, + "linux": { + "program": "./bin/gdbDebug.sh", + } + }] + ``` + +1. A combination of both approaches is possible too. The following example is from the Mono DA which is implemented as a mono application that needs a runtime on macOS and Linux but not on Windows: + + ```json + "debuggers": [{ + "type": "mono", + "program": "./bin/monoDebug.exe", + "osx": { + "runtime": "mono" + }, + "linux": { + "runtime": "mono" + } + }] + ``` + +**configurationAttributes** declares the schema for the `launch.json` attributes that are available for this debugger. This schema is used for validating the `launch.json` and supporting IntelliSense and hover help when editing the launch configuration. + +The **initialConfigurations** define the initial content of the default `launch.json` for this debugger. This information is used when a project does not have a `launch.json` and a user starts a debug session or clicks on the gear icon in the debug viewlet. In this case VS Code lets the user pick a debug environment and then creates the corresponding `launch.json`: + +![Debugger Quickpick](images/debugger-extension/debug-init-config.png) + +Instead of defining the initial content of the `launch.json` statically in the `package.json`, it is possible to compute the initial configurations dynamically by implementing a `DebugConfigurationProvider` (for details see the section [Using a DebugConfigurationProvider below](#using-a-debugconfigurationprovider)). + +**configurationSnippets** define launch configuration snippets that get surfaced in IntelliSense when editing the `launch.json`. As a convention, prefix the `label` attribute of a snippet by the debug environment name so that it can be clearly identified when presented in a list of many snippet proposals. + +The **variables** contribution binds "variables" to "commands". These variables can be used in the launch configuration using the **\${command:xyz}** syntax and the variables are substituted by the value returned from the bound command when a debug session is started. + +The implementation of a command lives in the extension and it can range from a simple expression with no UI, to sophisticated functionality based on the UI features available in the extension API. +Mock Debug binds a variable `AskForProgramName` to the command `extension.mock-debug.getProgramName`. The [implementation](https://github.com/Microsoft/vscode-mock-debug/blob/606454ff3bd669867a38d9b2dc7b348d324a3f6b/src/extension.ts#L21-L26) of this command in `src/extension.ts` uses the `showInputBox` to let the user enter a program name: + +```ts +vscode.commands.registerCommand('extension.mock-debug.getProgramName', config => { + return vscode.window.showInputBox({ + placeHolder: 'Please enter the name of a markdown file in the workspace folder', + value: 'readme.md' + }); +}); +``` + +The variable can now be used in any string typed value of a launch configuration as **\${command:AskForProgramName}**. + +## Using a DebugConfigurationProvider + +If the static nature of debug contributions in the `package.json` is not sufficient, a `DebugConfigurationProvider` can be used to dynamically control the following aspects of a debug extension: + +- The initial debug configurations for a newly created launch.json can be generated dynamically, e.g. based on some contextual information available in the workspace. +- A launch configuration can be _resolved_ (or modified) before it is used to start a new debug session. This allows for filling in default values based on information available in the workspace. + +The `MockConfigurationProvider` in `src/extension.ts` implements `resolveDebugConfiguration` to detect the case where a debug session is started when no launch.json exists, but a Markdown file is open in the active editor. This is a typical scenario where the user has a file open in the editor and just wants to debug it without creating a launch.json. + +A debug configuration provider is registered for a specific debug type via `vscode.debug.registerDebugConfigurationProvider`, typically in the extension's `activate` function. +To ensure that the `DebugConfigurationProvider` is registered early enough, the extension must be activated as soon as the debug functionality is used. This can be easily achieved by configuring extension activation for the `onDebug` event in the `package.json`: + +```json +"activationEvents": [ + "onDebug", + // ... +], +``` + +This catch-all `onDebug` is triggered as soon as any debug functionality is used. This works fine as long as the extension has cheap startup costs (i.e. does not spend a lot of time in its startup sequence). If a debug extension has an expensive startup (for instance because of starting a language server), the `onDebug` activation event could negatively affect other debug extensions, because it is triggered rather early and does not take a specific debug type into account. + +A better approach for expensive debug extensions is to use more fine-grained activation events: + +- `onDebugInitialConfigurations` is fired just before the `provideDebugConfigurations` method of the `DebugConfigurationProvider` is called. +- `onDebugResolve:type` is fired just before the `resolveDebugConfiguration` method of the `DebugConfigurationProvider` for the specified type is called. + +**Rule of thumb:** If activation of a debug extensions is cheap, use `onDebug`. If it is expensive, use `onDebugInitialConfigurations` and/or `onDebugResolve` depending on whether the `DebugConfigurationProvider` implements the corresponding methods `provideDebugConfigurations` and/or `resolveDebugConfiguration`. + +## Publishing your debugger extension + +Once you have created your debugger extension you can publish it to the Marketplace: + +- Update the attributes in the `package.json` to reflect the naming and purpose of your debugger extension. +- Upload to the Marketplace as described in [Publishing Extension](/api/working-with-extensions/publishing-extension). + +## Alternative approach to develop a debugger extension + +As we have seen, developing a debugger extension typically involves debugging both the extension and the debug adapter in two parallel sessions. As explained above VS Code supports this nicely but development could be easier if both the extension and the debug adapter would be one program that could be debugged in one debug session. + +This approach is in fact easily doable as long as your debug adapter is implemented in TypeScript/JavaScript. The basic idea is to run the debug adapter as a server inside the extension host and to make VS Code to connect to it instead of launching a new debug adapter per session. + +Mock Debug shows how a [DebugAdapterDescriptorFactory](https://github.com/Microsoft/vscode-mock-debug/blob/6a2ef01b95bb22cdf55683f4d616cad501051510/src/extension.ts#L74-L98) can be used to create and [register](https://github.com/Microsoft/vscode-mock-debug/blob/6a2ef01b95bb22cdf55683f4d616cad501051510/src/extension.ts#L32-L36) a server-based debug adapter. +The feature is enabled by setting the compile time flag [`EMBED_DEBUG_ADAPTER`](https://github.com/Microsoft/vscode-mock-debug/blob/6a2ef01b95bb22cdf55683f4d616cad501051510/src/extension.ts#L17) to true. If you now start debugging the extension with **F5** you will hit breakpoints not only in the extension host but in the debug adapter as well. diff --git a/api/extension-guides/file-system-provider.md b/api/extension-guides/file-system-provider.md new file mode 100644 index 0000000000000000000000000000000000000000..23e2e2ef86c8bd4de1e76d17b1f23a9b3f8a0038 --- /dev/null +++ b/api/extension-guides/file-system-provider.md @@ -0,0 +1,8 @@ +--- +DateApproved: +MetaDescription: +--- + +# File System Provider + +For https://github.com/Microsoft/vscode-extension-samples/tree/master/fsprovider-sample and https://github.com/Microsoft/vscode-extension-samples/tree/master/nodefs-provider-sample diff --git a/api/extension-guides/i18n.md b/api/extension-guides/i18n.md new file mode 100644 index 0000000000000000000000000000000000000000..014754bb8fa07dd49d1c2a9ae0e1b43337f02db9 --- /dev/null +++ b/api/extension-guides/i18n.md @@ -0,0 +1,8 @@ +--- +DateApproved: +MetaDescription: +--- + +# Internationalization + +https://github.com/Microsoft/vscode-extension-samples/tree/master/i18n-sample diff --git a/api/extension-guides/icon-theme.md b/api/extension-guides/icon-theme.md new file mode 100644 index 0000000000000000000000000000000000000000..38faaded2483535d279d42b628da9440a7f8ae70 --- /dev/null +++ b/api/extension-guides/icon-theme.md @@ -0,0 +1,160 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: f470466d-89b0-4115-ab7a-2448023b0a6d +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: A guide to creating Icon Theme in Visual Studio Code +--- + +# Icon Theme + +Visual Studio Code displays icons next to filenames throughout its UI, and extensions can contribute new sets of file icons that users can choose from. + +## Adding a new Icon Theme + +You can create your own icon theme from icons (preferably SVG) and from icon fonts. As example, check out the two built-in themes: [Minimal](https://github.com/Microsoft/vscode/tree/master/extensions/theme-defaults) and [Seti](https://github.com/Microsoft/vscode/tree/master/extensions/theme-seti). + +To begin, create a VS Code extension and add the `iconTheme` contribution point. + +```json +{ + "contributes": { + "iconThemes": [ + { + "id": "turtles", + "label": "Turtles", + "path": "./fileicons/turtles-icon-theme.json" + } + ] + } +} +``` + +The `id` is the identifier for the icon theme. It is currently only used internally. In the future, it might be used in the settings, so make it unique but also readable. `label` is shown in the icon theme picker drop-down. The `path` points to a file in the extension that defines the icon set. If your icon set name follows the `*icon-theme.json` name scheme, you will get completion support and hovers in VS Code. + +### Icon Set File + +The icon set file is a JSON file consisting of file icon associations and icon definitions. + +An icon association maps a file type ('file', 'folder', 'json-file'...) to an icon definition. Icon definitions define where the icon is located: That can be an image file or also glyph in a font. + +### Icon definitions + +The `iconDefinitions` section contains all definitions. Each definition has an id, which will be used to reference the definition. A definition can be referenced also by more than one file association. + +```json +{ + "iconDefinitions": { + "_folder_dark": { + "iconPath": "./images/Folder_16x_inverse.svg" + } + } +} +``` + +This icon definition above contains a definition with the identifier `_folder_dark`. + +The following properties are supported: + +- `iconPath`: When using a svg/png: the path to the image. +- `fontCharacter`: When using a glyph font: The character in the font to use. +- `fontColor`: When using a glyph font: The color to use for the glyph. +- `fontSize`: When using a font: The font size. By default, the size specified in the font specification is used. Should be a relative size (e.g. 150%) to the parent font size. +- `fontId`: When using a font: The id of the font. If not specified, the first font specified in font specification section will be picked. + +### File association + +Icons can be associated to folders, folder names, files, file extensions, file names and [language ids](/api/references/contribution-points#contributes.languages). + +Additionally each of these associations can be refined for 'light' and 'highContrast' color themes. + +Each file association points to an icon definition. + +```json +{ + "file": "_file_dark", + "folder": "_folder_dark", + "folderExpanded": "_folder_open_dark", + "folderNames": { + ".vscode": "_vscode_folder" + }, + "fileExtensions": { + "ini": "_ini_file" + }, + "fileNames": { + "win.ini": "_win_ini_file" + }, + "languageIds": { + "ini": "_ini_file" + }, + "light": { + "folderExpanded": "_folder_open_light", + "folder": "_folder_light", + "file": "_file_light", + "fileExtensions": { + "ini": "_ini_file_light" + } + }, + "highContrast": {} +} +``` + +- `file` is the default file icon, shown for all files that don't match any extension, filename or language id. Currently all properties defined by the definition of the file icon will be inherited (only relevant for font glyphs, useful for the fontSize). +- `folder` is the folder icon for collapsed folders, and if `folderExpanded` is not set, also for expanded folders. Icons for specific folder names can be associated using the `folderNames` property. + The folder icon is optional. If not set, no icon will be shown for folder. +- `folderExpanded` is the folder icon for expanded folders. The expanded folder icon is optional. If not set, the icon defined for `folder` will be shown. +- `folderNames` associates folder names to icons. The key of the set is the folder name, not including any path segments. Patterns or wildcards are not supported. Folder name matching is case insensitive. +- `folderNamesExpanded` associates folder names to icons for expanded folder. The key of the set is the folder name, not including any path segments. Patterns or wildcards are not supported. Folder name matching is case insensitive. +- `rootFolder` is the folder icon for collapsed workspace root folders , and if `rootFolderExpanded` is not set, also for expanded workspace root folders. If not set, the icon defined for `folder` will be shown for workspace root folders. +- `rootFolderExpanded` is the folder icon for expanded workspace root folders. If not set, the icon defined for `rootFolder` will be shown for exanded workspace root folders. +- `languageIds` associates languages to icons. The key in the set is the language id as defined in the [language contribution point](/api/references/contribution-points#contributes.languages). The language of a file is evaluated based on the file extensions and file names as defined in the language contribution. Note that the 'first line match' of the language contribution is not considered. +- `fileExtensions` associates file extensions to icons. The key in the set is the file extension name. The extension name is a file name segment after a dot (not including the dot). File names with multiple dots such as `lib.d.ts` can match multiple extensions; 'd.ts' and 'ts'. Extensions are compared case insensitive. +- `fileNames` associates file names to icons. The key in the set is the full file name, not including any path segments. Patterns or wildcards are not supported. File name matching is case insensitive. A 'fileName' match is the strongest match, and the icon associated to the file name will be preferred over an icon of a matching fileExtension and also of a matching language Id. + +A file extension match is preferred over a language match, but is weaker than a file name match. + +The `light` and the `highContrast` section have the same file association properties as just listed. They allow to override icons for the corresponding themes. + +### Font definitions + +The `fonts` section lets you declare any number of glyph fonts that you want to use. +You can later reference these fonts in the icon definitions. The font declared first will be used as the default if an icon definition does not specify a font id. + +Copy the font file into your extension and set the path accordingly. +It is recommended to use [WOFF](https://developer.mozilla.org/docs/Web/Guide/WOFF) fonts. + +- Set 'woff' as the format. +- the weight property values are defined [here](https://developer.mozilla.org/docs/Web/CSS/font-weight#Values). +- the style property values are defined [here](https://developer.mozilla.org/docs/Web/CSS/@font-face/font-style#Values). +- the size should be relative to the font size where the icon is used. Therefore, always use percentage. + +```json +{ + "fonts": [ + { + "id": "turtles-font", + "src": [ + { + "path": "./turtles.woff", + "format": "woff" + } + ], + "weight": "normal", + "style": "normal", + "size": "150%" + } + ], + "iconDefinitions": { + "_file": { + "fontCharacter": "\\E002", + "fontColor": "#5f8b3b", + "fontId": "turtles-font" + } + } +} +``` + +### Folder icons in File Icon Themes + +File Icon themes can instruct the File Explorer not to show the default folder icon (the rotating triangles or "twisties") when the folder icons are good enough to indicate the expansion state of a folder. This mode is enabled by setting `"hidesExplorerArrows":true` in the File Icon theme definition file. diff --git a/api/extension-guides/images/color-theme/color-setting.png b/api/extension-guides/images/color-theme/color-setting.png new file mode 100644 index 0000000000000000000000000000000000000000..170c9effb66406ff51ed688db66b9a0352f04360 --- /dev/null +++ b/api/extension-guides/images/color-theme/color-setting.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3e33b786a5cb42ababa7e6b95c1588a4e118a9c6cca4d702744f8c180b710379 +size 272836 diff --git a/api/extension-guides/images/color-theme/mytheme.png b/api/extension-guides/images/color-theme/mytheme.png new file mode 100644 index 0000000000000000000000000000000000000000..1a3673ff61fe0bb5f9ddf76baac2b56331717585 Binary files /dev/null and b/api/extension-guides/images/color-theme/mytheme.png differ diff --git a/api/extension-guides/images/color-theme/tm-inspector.png b/api/extension-guides/images/color-theme/tm-inspector.png new file mode 100644 index 0000000000000000000000000000000000000000..ef3bcfa64d110a97a7084ec71614516c3bde800d --- /dev/null +++ b/api/extension-guides/images/color-theme/tm-inspector.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:38c9f842e34507294d648d60dece29479cec9be8f93df5b04ac830cfceb110e7 +size 203332 diff --git a/api/extension-guides/images/color-theme/yocode-colortheme.png b/api/extension-guides/images/color-theme/yocode-colortheme.png new file mode 100644 index 0000000000000000000000000000000000000000..248277286847cb11f9fdad3b3d2dda1fbe14fe7d Binary files /dev/null and b/api/extension-guides/images/color-theme/yocode-colortheme.png differ diff --git a/api/extension-guides/images/commands/palette.png b/api/extension-guides/images/commands/palette.png new file mode 100644 index 0000000000000000000000000000000000000000..8bd2ce8a3105da532eb50ece58958db28e67ee00 Binary files /dev/null and b/api/extension-guides/images/commands/palette.png differ diff --git a/api/extension-guides/images/debugger-extension/debug-arch1.png b/api/extension-guides/images/debugger-extension/debug-arch1.png new file mode 100644 index 0000000000000000000000000000000000000000..d6af0b6bd64983598cc2454915a4440b8c405a4c Binary files /dev/null and b/api/extension-guides/images/debugger-extension/debug-arch1.png differ diff --git a/api/extension-guides/images/debugger-extension/debug-arch2.png b/api/extension-guides/images/debugger-extension/debug-arch2.png new file mode 100644 index 0000000000000000000000000000000000000000..22e47dcc576e52aeda5a3e1f7e6093a8a06facea Binary files /dev/null and b/api/extension-guides/images/debugger-extension/debug-arch2.png differ diff --git a/api/extension-guides/images/debugger-extension/debug-features.png b/api/extension-guides/images/debugger-extension/debug-features.png new file mode 100644 index 0000000000000000000000000000000000000000..2fd3e66f188f4851fa9cd043e9043d9a47b525a3 --- /dev/null +++ b/api/extension-guides/images/debugger-extension/debug-features.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:085536ca6bc19742828c0cdee02b5c7f013686d9c3fb92d7fbb57029a774d88f +size 295752 diff --git a/api/extension-guides/images/debugger-extension/debug-init-config.png b/api/extension-guides/images/debugger-extension/debug-init-config.png new file mode 100644 index 0000000000000000000000000000000000000000..cd71c214231e631ffaf02fe7189f5d1007cd3eb4 Binary files /dev/null and b/api/extension-guides/images/debugger-extension/debug-init-config.png differ diff --git a/api/extension-guides/images/debugger-extension/debug-mock-session.png b/api/extension-guides/images/debugger-extension/debug-mock-session.png new file mode 100644 index 0000000000000000000000000000000000000000..98c51461c6bb92ce4593d31637d1ba0e45ad253c Binary files /dev/null and b/api/extension-guides/images/debugger-extension/debug-mock-session.png differ diff --git a/api/extension-guides/images/debugger-extension/debugger-extension-server.png b/api/extension-guides/images/debugger-extension/debugger-extension-server.png new file mode 100644 index 0000000000000000000000000000000000000000..e2d04968fe36f421186d74b2b494e89d0be27cae --- /dev/null +++ b/api/extension-guides/images/debugger-extension/debugger-extension-server.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3b5f4be4fb2d8ad12f6722c57eb6b58363d09960d823b2afe4f1dac72b7be397 +size 134016 diff --git a/api/extension-guides/images/debugger-extension/mock-debug.gif b/api/extension-guides/images/debugger-extension/mock-debug.gif new file mode 100644 index 0000000000000000000000000000000000000000..0a013a2f8ab2953b9f7be59dda4edb1d689904c2 --- /dev/null +++ b/api/extension-guides/images/debugger-extension/mock-debug.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4315f93fe647e71568cbaa7d8e7297875040c1db4ed336ccc9c32e9f492db0d1 +size 154049 diff --git a/api/extension-guides/images/scm-provider/main.png b/api/extension-guides/images/scm-provider/main.png new file mode 100644 index 0000000000000000000000000000000000000000..244cbae03b65fb34ad2648a960f276d1e943ee01 Binary files /dev/null and b/api/extension-guides/images/scm-provider/main.png differ diff --git a/api/extension-guides/images/scm-provider/menus.png b/api/extension-guides/images/scm-provider/menus.png new file mode 100644 index 0000000000000000000000000000000000000000..4dc13c1924a11bb27185bc033a180a1c1e866a2e Binary files /dev/null and b/api/extension-guides/images/scm-provider/menus.png differ diff --git a/api/extension-guides/images/scm-provider/quickdiff.png b/api/extension-guides/images/scm-provider/quickdiff.png new file mode 100644 index 0000000000000000000000000000000000000000..c980dfa78b392a4622f8d782cb0d0afe54279040 Binary files /dev/null and b/api/extension-guides/images/scm-provider/quickdiff.png differ diff --git a/api/extension-guides/images/scm-provider/sourcecontrol-menu.png b/api/extension-guides/images/scm-provider/sourcecontrol-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..32c977a02738d299e01954de6787214656ac1f6c Binary files /dev/null and b/api/extension-guides/images/scm-provider/sourcecontrol-menu.png differ diff --git a/api/extension-guides/images/tree-view/view-actions.png b/api/extension-guides/images/tree-view/view-actions.png new file mode 100644 index 0000000000000000000000000000000000000000..d63fc25b0e141c1ef317d4e183e4ea10771ac585 Binary files /dev/null and b/api/extension-guides/images/tree-view/view-actions.png differ diff --git a/api/extension-guides/images/tree-view/view-container.png b/api/extension-guides/images/tree-view/view-container.png new file mode 100644 index 0000000000000000000000000000000000000000..82e7f5a0505effc811d9a8aa4b35c07ddee500e6 --- /dev/null +++ b/api/extension-guides/images/tree-view/view-container.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:74c51920a7f9c98aa6342011b7f61258fdbb4b62cce8b6c5fad28b9cca2ef737 +size 290751 diff --git a/api/extension-guides/images/tree-view/view.png b/api/extension-guides/images/tree-view/view.png new file mode 100644 index 0000000000000000000000000000000000000000..9dbba04036ae5dd15d237eb3c17a8e5d385f3667 Binary files /dev/null and b/api/extension-guides/images/tree-view/view.png differ diff --git a/api/extension-guides/images/virtual-documents/cowsay-bwd.png b/api/extension-guides/images/virtual-documents/cowsay-bwd.png new file mode 100644 index 0000000000000000000000000000000000000000..d32795de2c1efded24fe2900c3106cc29fbdf3cd Binary files /dev/null and b/api/extension-guides/images/virtual-documents/cowsay-bwd.png differ diff --git a/api/extension-guides/images/webview/basics-developer_tools.png b/api/extension-guides/images/webview/basics-developer_tools.png new file mode 100644 index 0000000000000000000000000000000000000000..dd74ce31ae9e87584a1d2a914cbf1bdf55b20918 --- /dev/null +++ b/api/extension-guides/images/webview/basics-developer_tools.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ebc3aa5e2d941b410b02f06a6182fc1b685d1ebd24a6605da9550d6a808a1516 +size 219184 diff --git a/api/extension-guides/images/webview/basics-drag.gif b/api/extension-guides/images/webview/basics-drag.gif new file mode 100644 index 0000000000000000000000000000000000000000..64ead1eae0b46a48d7d9dd903e04e3f3dc92635e --- /dev/null +++ b/api/extension-guides/images/webview/basics-drag.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6b7c66d2a0ad3d0da8c3bba86fcdbeb5979f863e88349a2b7752838ec80ddfa0 +size 2933557 diff --git a/api/extension-guides/images/webview/basics-html.png b/api/extension-guides/images/webview/basics-html.png new file mode 100644 index 0000000000000000000000000000000000000000..e8e147a6949784a841cbeec5bfe08829f699ed93 --- /dev/null +++ b/api/extension-guides/images/webview/basics-html.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:686667a12313d31ffe7c30d9d2ef31d05766a729e6e9c702362a845048f65179 +size 135389 diff --git a/api/extension-guides/images/webview/basics-no_content.png b/api/extension-guides/images/webview/basics-no_content.png new file mode 100644 index 0000000000000000000000000000000000000000..3a87aba8844a8802a760f22840faec3fba474371 Binary files /dev/null and b/api/extension-guides/images/webview/basics-no_content.png differ diff --git a/api/extension-guides/images/webview/basics-ondidchangeviewstate.gif b/api/extension-guides/images/webview/basics-ondidchangeviewstate.gif new file mode 100644 index 0000000000000000000000000000000000000000..92c5c61264021139cefc7c4375e1f84e2ca67dba --- /dev/null +++ b/api/extension-guides/images/webview/basics-ondidchangeviewstate.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:16588bcda79469423503d5f0c9e6fe8be26b2af270889328a48552b82a86dae4 +size 3508124 diff --git a/api/extension-guides/images/webview/basics-restore.gif b/api/extension-guides/images/webview/basics-restore.gif new file mode 100644 index 0000000000000000000000000000000000000000..c016709aa744d0928ef688a3b6e76f1f37c504c7 --- /dev/null +++ b/api/extension-guides/images/webview/basics-restore.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:63608084786607862bb87ba9cf678e9e3e6b93b9aa38696f4279fbbe9c51d823 +size 1782364 diff --git a/api/extension-guides/images/webview/basics-single_panel.gif b/api/extension-guides/images/webview/basics-single_panel.gif new file mode 100644 index 0000000000000000000000000000000000000000..d06102c6ffc23e7344250c1fc1d42a4a123998e3 --- /dev/null +++ b/api/extension-guides/images/webview/basics-single_panel.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:401215894ce1288485c7f35f56e5137b8388a5fa0b55cf268ff2a5696f7b5721 +size 1695365 diff --git a/api/extension-guides/images/webview/basics-update.gif b/api/extension-guides/images/webview/basics-update.gif new file mode 100644 index 0000000000000000000000000000000000000000..d062cfc6040e81184948660952aca141f7322901 --- /dev/null +++ b/api/extension-guides/images/webview/basics-update.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:99b4b60c1692d04fed0bf8efc54fad95c87b387aa5a024ac141857e3107713df +size 2491751 diff --git a/api/extension-guides/images/webview/debug-active-frame.png b/api/extension-guides/images/webview/debug-active-frame.png new file mode 100644 index 0000000000000000000000000000000000000000..10f8e21ded211f3678c6ddc2932fe318fa91ec3d Binary files /dev/null and b/api/extension-guides/images/webview/debug-active-frame.png differ diff --git a/api/extension-guides/images/webview/persistence-retrain.gif b/api/extension-guides/images/webview/persistence-retrain.gif new file mode 100644 index 0000000000000000000000000000000000000000..3062d23505e932649034ed35250a73146c30d81f --- /dev/null +++ b/api/extension-guides/images/webview/persistence-retrain.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f63795044995ea1006c530b3609790884daaf8a358ce87e2593e5b7d43a6a2da +size 2452603 diff --git a/api/extension-guides/images/webview/scripts-basic.gif b/api/extension-guides/images/webview/scripts-basic.gif new file mode 100644 index 0000000000000000000000000000000000000000..58da985a0aaae9ecc07259e214e79f12026ca277 --- /dev/null +++ b/api/extension-guides/images/webview/scripts-basic.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6df523a70c90b6537519d2fcb05ab526f5129ca5c1a0ee2c3b60d6f3ae708229 +size 1462384 diff --git a/api/extension-guides/images/webview/scripts-extension_to_webview.gif b/api/extension-guides/images/webview/scripts-extension_to_webview.gif new file mode 100644 index 0000000000000000000000000000000000000000..6497e83d5ff24d2879cf3667b2d0e707d6e65574 --- /dev/null +++ b/api/extension-guides/images/webview/scripts-extension_to_webview.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:84e5dc0889a2c38df66f5e823a6593a0ccdd20e6a2abf31cadf9e1c393147140 +size 1913275 diff --git a/api/extension-guides/images/webview/scripts-webview_to_extension.gif b/api/extension-guides/images/webview/scripts-webview_to_extension.gif new file mode 100644 index 0000000000000000000000000000000000000000..7fbff31e9a821de1d8cefe66356749a7860d3b50 --- /dev/null +++ b/api/extension-guides/images/webview/scripts-webview_to_extension.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:74221dac8e7a0bc3b1419d32e734aa2b84dc6567134759720ab732efe8f85fac +size 2727491 diff --git a/api/extension-guides/markdown-extension.md b/api/extension-guides/markdown-extension.md new file mode 100644 index 0000000000000000000000000000000000000000..3f3320a926db4c3372dd6546b9b821f2d995abb4 --- /dev/null +++ b/api/extension-guides/markdown-extension.md @@ -0,0 +1,87 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 1664249a-ba7a-4a53-b3f0-9d757cff7d27 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Learn how to extend Visual Studio Code's built-in Markdown preview. +--- + +# Markdown Extension + +Markdown extensions allow you to extend and enhance Visual Studio Code's built-in Markdown preview. This includes changing the look of the preview or adding support for new Markdown syntax. + +## Changing the look of the Markdown preview with CSS + +Extensions can contribute CSS to change the look or layout of the Markdown preview. Stylesheets are registered using the `markdown.previewStyles` [Contribution Point](/api/references/contribution-points) in the extension's `package.json`: + +```json +"contributes": { + "markdown.previewStyles": [ + "./style.css" + ] +} +``` + +`"markdown.previewStyles"` is a list of files relative to the extension's root folder. + +Contributed styles are added after the built-in Markdown preview styles but before a user's `"markdown.styles"`. + +The [Markdown Preview GitHub Styling](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles) extension is a good example that demonstrates using a stylesheet to make the Markdown preview look like GitHub's rendered Markdown. You can review the extension's source code on [GitHub](https://github.com/mjbvz/vscode-github-markdown-preview-style). + +## Adding support for new syntax with markdown-it plugins + +The VS Code Markdown preview supports the [CommonMark specification](https://spec.commonmark.org). Extensions can add support for additional Markdown syntax by contributing a [markdown-it plugin.](https://github.com/markdown-it/markdown-it#syntax-extensions) + +To contribute a markdown-it plugin, first add a `"markdown.markdownItPlugins"` contribution in your extension's `package.json`: + +```json +"contributes": { + "markdown.markdownItPlugins": true +} +``` + +Then, in the extension's main `activation` function, return an object with a function named `extendMarkdownIt`. This function takes the current markdown-it instance and must return a new markdown-it instance: + +```ts +import * as vscode from 'vscode'; + +export function activate(context: vscode.ExtensionContext) { + return { + extendMarkdownIt(md: any) { + return md.use(require('markdown-it-emoji')); + } + }; +} +``` + +To contribute multiple markdown-it plugins, simply return multiple `use` statements chained together: + +```ts +return md.use(require('markdown-it-emoji')).use(require('markdown-it-hashtag')); +``` + +Extensions that contribute markdown-it plugins are activated lazily, when a Markdown preview is shown for the first time. + +The [markdown-emoji](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-emoji) extension demonstrates using a markdown-it plugin to add emoji support to the markdown preview. You can review the Emoji extension's source code on [GitHub](https://github.com/mjbvz/vscode-markdown-emoji). + +You may also want to review: + +- [Guidelines](https://github.com/markdown-it/markdown-it/blob/master/docs/development.md) for markdown-it plugin developers +- [Existing markdown-it plugins](https://www.npmjs.com/browse/keyword/markdown-it-plugin) + +## Adding advanced functionality with scripts + +For advanced functionality, extensions may contribute scripts that are executed inside of the Markdown preview. + +```json +"contributes": { + "markdown.previewScripts": [ + "./main.js" + ] +} +``` + +Contributed scripts are loaded asynchronously and reloaded on every content change. + +The [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) extension demonstrates using scripts to add [mermaid](https://knsv.github.io/mermaid/index.html) diagrams and flowchart support to the markdown preview. You can review the Mermaid extension's source code on [GitHub](https://github.com/mjbvz/vscode-markdown-mermaid). diff --git a/api/extension-guides/overview.md b/api/extension-guides/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..9e043cadcfd00e3f31e4b4567c2fd675ac1caaf9 --- /dev/null +++ b/api/extension-guides/overview.md @@ -0,0 +1,54 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: B32601A8-27ED-4D97-BA83-F1C8C945C635 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Learn from Visual Studio Code extension guides and code samples +--- + +# Extension Guides + +Once you have learned the basics of Visual Studio Code Extension API in the [Hello World](/api/get-started/your-first-extension) sample, it's time to build some real-world extensions. While the [Extension Capabilities](/api/extension-capabilities/overview) section offers high-level overviews of what extension **can** do, this section contains a list of detailed code guides and samples that explains **how** to use a specific VS Code API. + +In each guide-sample combo, you can expect to find: + +- Thoroughly commented source code. +- A gif or image showing the usage of the sample extension. +- Instructions for running the sample extension. +- Listing of VS Code API being used. +- Listing of Contribution Points being used. +- Real-world extensions resembling the sample. +- Explanation of API concepts. + +## Guides & Samples + +Here is a list of guides and samples. While each guide comes with sample code, some samples do not have a matching guide yet. + +Each sample illustrates one [VS Code API](/api/references/vscode-api) usage or a [Contribution Point](/api/references/contribution-points). + +| Sample | Guide on VS Code Website | API & Contribution | +| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Webview Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/webview-sample) | [/api/extension-guides/webview](https://code.visualstudio.com/api/extension-guides/webview) | [window.createWebviewPanel](https://code.visualstudio.com/api/references/vscode-api#window.createWebviewPanel)
[window.registerWebviewPanelSerializer](https://code.visualstudio.com/api/references/vscode-api#window.registerWebviewPanelSerializer) | +| [Status Bar Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/statusbar-sample) | N/A | [window.createStatusBarItem](https://code.visualstudio.com/api/references/vscode-api#window.createStatusBarItem)
[StatusBarItem](https://code.visualstudio.com/api/references/vscode-api#StatusBarItem) | +| [Tree View Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/tree-view-sample) | [/api/extension-guides/tree-view](https://code.visualstudio.com/api/extension-guides/tree-view) | [window.createTreeView](https://code.visualstudio.com/api/references/vscode-api#window.createTreeView)
[window.registerTreeDataProvider](https://code.visualstudio.com/api/references/vscode-api#window.registerTreeDataProvider)
[TreeView](https://code.visualstudio.com/api/references/vscode-api#TreeView)
[TreeDataProvider](https://code.visualstudio.com/api/references/vscode-api#TreeDataProvider)
[contributes.views](https://code.visualstudio.com/api/references/contribution-points#contributes.views)
[contributes.viewsContainers](https://code.visualstudio.com/api/references/contribution-points#contributes.viewsContainers) | +| [Task Provider Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/task-provider-sample) | [/api/extension-guides/task-provider](https://code.visualstudio.com/api/extension-guides/task-provider) | [tasks.registerTaskProvider](https://code.visualstudio.com/api/references/vscode-api#tasks.registerTaskProvider)
[Task](https://code.visualstudio.com/api/references/vscode-api#Task)
[ShellExecution](https://code.visualstudio.com/api/references/vscode-api#ShellExecution)
[contributes.taskDefinitions](https://code.visualstudio.com/api/references/contribution-points#contributes.taskDefinitions) | +| [Multi Root Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/basic-multi-root-sample) | N/A | [workspace.getWorkspaceFolder](https://code.visualstudio.com/api/references/vscode-api#workspace.getWorkspaceFolder)
[workspace.onDidChangeWorkspaceFolders](https://code.visualstudio.com/api/references/vscode-api#workspace.onDidChangeWorkspaceFolders) | +| [Completion Provider Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/completions-sample) | N/A | [languages.registerCompletionItemProvider](https://code.visualstudio.com/api/references/vscode-api#languages.registerCompletionItemProvider)
[CompletionItem](https://code.visualstudio.com/api/references/vscode-api#CompletionItem)
[SnippetString](https://code.visualstudio.com/api/references/vscode-api#SnippetString) | +| [File System Provider Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/fsprovider-sample) | N/A | [workspace.registerFileSystemProvider](https://code.visualstudio.com/api/references/vscode-api#workspace.registerFileSystemProvider) | +| [Editor Decorator Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/decorator-sample) | N/A | [TextEditor.setDecorations](https://code.visualstudio.com/api/references/vscode-api#TextEditor.setDecorations)
[DecorationOptions](https://code.visualstudio.com/api/references/vscode-api#DecorationOptions)
[DecorationInstanceRenderOptions](https://code.visualstudio.com/api/references/vscode-api#DecorationInstanceRenderOptions)
[ThemableDecorationInstanceRenderOptions](https://code.visualstudio.com/api/references/vscode-api#ThemableDecorationInstanceRenderOptions)
[window.createTextEditorDecorationType](https://code.visualstudio.com/api/references/vscode-api#window.createTextEditorDecorationType)
[TextEditorDecorationType](https://code.visualstudio.com/api/references/vscode-api#TextEditorDecorationType)
[contributes.colors](https://code.visualstudio.com/api/references/contribution-points#contributes.colors) | +| [I18n Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/i18n-sample) | N/A | | +| [Terminal Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/terminal-sample) | N/A | [window.createTerminal](https://code.visualstudio.com/api/references/vscode-api#window.createTerminal)
[window.onDidChangeActiveTerminal](https://code.visualstudio.com/api/references/vscode-api#window.onDidChangeActiveTerminal)
[window.onDidCloseTerminal](https://code.visualstudio.com/api/references/vscode-api#window.onDidCloseTerminal)
[window.onDidOpenTerminal](https://code.visualstudio.com/api/references/vscode-api#window.onDidOpenTerminal)
[window.Terminal](https://code.visualstudio.com/api/references/vscode-api#window.Terminal)
[window.terminals](https://code.visualstudio.com/api/references/vscode-api#window.terminals) | +| [Vim Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/vim-sample) | N/A | [commands](https://code.visualstudio.com/api/references/vscode-api#commands)
[StatusBarItem](https://code.visualstudio.com/api/references/vscode-api#StatusBarItem)
[window.createStatusBarItem](https://code.visualstudio.com/api/references/vscode-api#window.createStatusBarItem)
[TextEditorCursorStyle](https://code.visualstudio.com/api/references/vscode-api#TextEditorCursorStyle)
[window.activeTextEditor](https://code.visualstudio.com/api/references/vscode-api#window.activeTextEditor)
[Position](https://code.visualstudio.com/api/references/vscode-api#Position)
[Range](https://code.visualstudio.com/api/references/vscode-api#Range)
[Selection](https://code.visualstudio.com/api/references/vscode-api#Selection)
[TextEditor](https://code.visualstudio.com/api/references/vscode-api#TextEditor)
[TextEditorRevealType](https://code.visualstudio.com/api/references/vscode-api#TextEditorRevealType)
[TextDocument](https://code.visualstudio.com/api/references/vscode-api#TextDocument) | + +## Language Extension Samples + +These samples are [Language Extensions](/api/language-extensions/overview) samples: + +| Sample | Guide on VS Code Website | +| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Snippet Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/snippet-sample) | [/api/language-extensions/snippet-guide](https://code.visualstudio.com/api/language-extensions/snippet-guide) | [contributes.snippets](https://code.visualstudio.com/api/references/contribution-points#contributes.snippets) | +| [Language Configuration Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/language-configuration-sample) | [/api/language-extensions/language-configuration-guide](https://code.visualstudio.com/api/language-extensions/language-configuration-guide) | [contributes.languages](https://code.visualstudio.com/api/references/contribution-points#contributes.languages) | +| [LSP Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/lsp-sample) | [/api/language-extensions/language-server-extension-guide](https://code.visualstudio.com/api/language-extensions/language-server-extension-guide) | | +| [LSP Log Streaming Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/lsp-log-streaming-sample) | N/A | | +| [LSP Multi Root Server Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/lsp-multi-server-sample) | https://github.com/Microsoft/vscode/wiki/Adopting-Multi-Root-Workspace-APIs#language-client--language-server | | diff --git a/api/extension-guides/scm-provider.md b/api/extension-guides/scm-provider.md new file mode 100644 index 0000000000000000000000000000000000000000..5c72ae5d6c5690ba709822fbbcfb8c38218da417 --- /dev/null +++ b/api/extension-guides/scm-provider.md @@ -0,0 +1,188 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 79996489-8D16-4C0A-8BE8-FF4B1E9C223A +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: A guide illustrating how to use Source Control API. +--- + +# Source Control API + +The Source Control API allows extension authors to define Source Control Management (SCM) features. There is a slim, yet powerful API surface which allows many different SCM systems to be integrated in Visual Studio Code, while having a common user interface with all of them. + +![VS Code SCM](images/scm-provider/main.png) + +VS Code itself ships with one Source Control provider, the Git extension, which is the best reference for this API and is [a great starting point](https://github.com/Microsoft/vscode/blob/master/extensions/git/src/repository.ts) if you'd like to contribute your very own SCM provider. There are other great examples in the Marketplace such as the [SVN extension](https://marketplace.visualstudio.com/items?itemName=johnstoncode.svn-scm). + +This documentation will help you build an extension which can make any SCM system work with VS Code. + +> **Note:** that you can always refer to the [`vscode` namespace API reference](/api/references/vscode-api#scm) in our documentation. + +## Source Control Model + +A `SourceControl` is the entity responsible for populating the Source Control model with **resource states**, instances of `SourceControlResourceState`. Resource states are themselves organized in **groups**, instances of `SourceControlResourceGroup`. + +You can create a new SourceControl with `vscode.scm.createSourceControl`. + +In order to better understand how these three entities correlate with each other, let's take [Git](https://github.com/Microsoft/vscode/tree/master/extensions/git) as an example. Consider the following output of `git status`: + +```bash +vsce master* → git status +On branch master +Your branch is up-to-date with 'origin/master'. +Changes to be committed: + (use "git reset HEAD ..." to unstage) + + modified: README.md + renamed: src/api.ts -> src/test/api.ts + +Changes not staged for commit: + (use "git add/rm ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + deleted: .travis.yml + modified: README.md +``` + +There are many things going on in this workspace. First, the `README.md` file has been modified, staged and then modified once again. Second, the `src/api.ts` file has been moved to `src/test/api.ts` and that move was staged. Finally, the `.travis.yml` file has been deleted. + +For this workspace, Git defines two resource groups: the **working tree** and the **index**. Each **file change** within that group is **resource state**: + +- **Index** - resource group + - `README.md`, modified - resource state + - `src/test/api.ts`, renamed from `src/api.ts` - resource state +- **Working Tree** - resource group + - `.travis.yml`, deleted - resource state + - `README.md`, modified - resource state + +Note how the same file, `README.md`, is part of two distinct resource states. + +Here's how Git creates this model: + +```ts +function createResourceUri(relativePath: string): vscode.Uri { + const absolutePath = path.join(vscode.workspace.rootPath, relativePath); + return vscode.Uri.file(absolutePath); +} + +const gitSCM = vscode.scm.createSourceControl('git', 'Git'); + +const index = gitSCM.createResourceGroup('index', 'Index'); +index.resourceStates = [ + { resourceUri: createResourceUri('README.md') }, + { resourceUri: createResourceUri('src/test/api.ts') } +]; + +const workingTree = gitSCM.createResourceGroup('workingTree', 'Changes'); +workingTree.resourceStates = [ + { resourceUri: createResourceUri('.travis.yml') }, + { resourceUri: createResourceUri('README.md') } +]; +``` + +Changes made to the source control and resource groups will be propagated to the Source Control view. + +## Source Control View + +VS Code is able to populate the Source Control view, as the Source Control model changes. Resource states are customizable using `SourceControlResourceDecorations`: + +```ts +export interface SourceControlResourceState { + readonly decorations?: SourceControlResourceDecorations; +} +``` + +The previous example would be sufficient to populate a simple list in the Source Control view, but there are many user interactions that the user might want to perform with each resource. For instance, what happens when the user clicks a resource state? The resource state can optionally provide a command to handle this action: + +```ts +export interface SourceControlResourceState { + readonly command?: Command; +} +``` + +### Menus + +There are five Source Control menu ids where you can place menu items, in order to provide the user with a much richer user interface. + +The `scm/title` menu is located to the right of the SCM view title. The menu items in the `navigation` group will be inline, while all the others will be within the `…` drop-down menu. + +The `scm/resourceGroup/context` and `scm/resourceState/context` are similar. The former will let you customize resource groups, while the later refers to resource states. Place menu items in the `inline` group to have them inline. All other menu item groups will be represented in a context menu usually accessible using the mouse right-click. Commands called from within these menus will have the respective resource states on passed as arguments. Note that the SCM view supports multiple selection thus a command might receive more than one resource at a time in its arguments. + +For example, Git supports staging multiple files by adding the `git.stage` command to the `scm/resourceState/context` menu and using such a method declaration: + +```ts +stage(...resourceStates: SourceControlResourceState[]): Promise; +``` + +When creating them, `SourceControl` and `SourceControlResourceGroup` instances require you to provide an `id` string. These values will be populated in the `scmProvider` and `scmResourceGroup` context keys, respectively. You can rely on these [context keys](/docs/getstarted/keybindings#_when-clause-contexts) in the `when` clauses of your menu items. Here's how Git is able to show a menu item for its `git.stage` command: + +```json +{ + "command": "git.stage", + "when": "scmProvider == git && scmResourceGroup == merge", + "group": "inline" +} +``` + +The `scm/change/title` allows you to contribute commands to the title bar of an inline change. The command will be passed as arguments the URI of the document, the array of changes within it, and the index of the change which the inline change affordance is currently focused on. For example, here's the declaration of the `stageChange` Git command, which is contributed to this menu: + +```ts +async stageChange(uri: Uri, changes: LineChange[], index: number): Promise; +``` + +The `scm/sourceControl` menu is located contextually near SourceControl instances: + +![source control menu](images/scm-provider/sourcecontrol-menu.png) + +Finally, the `scm/change/title` menu is related to the Quick Diff experience, showcased further ahead. It lets you contribute commands which are specific to code changes. + +### SCM Input Box + +The Source Control Input Box, located atop of each Source Control view, allows the user to input a message. You can get (and set) this message in order to perform operations. In Git, for example, this is used as the commit box, in which users type in commit messages and `git commit` commands pick them up. + +```ts +export interface SourceControlInputBox { + value: string; +} + +export interface SourceControl { + readonly inputBox: SourceControlInputBox; +} +``` + +The user can type Ctrl+Enter (or Cmd+Enter on macOS) to accept any message. You can handle this event by providing a `acceptInputCommand` to your `SourceControl` instance. + +```ts +export interface SourceControl { + readonly acceptInputCommand?: Command; +} +``` + +## Quick Diff + +VS Code also supports displaying **quick diff** editor gutter decorations. Clicking those decorations will reveal an inline diff experience, to which you can contribute contextual commands: + +![SCM quick diff](images/scm-provider/quickdiff.png) + +These decorations are computed by VS Code itself. All you need to do is provide VS Code with the original contents of any given file. + +```ts +export interface SourceControl { + quickDiffProvider?: QuickDiffProvider; +} +``` + +Using a `QuickDiffProvider`, your implementation is able to tell VS Code what's the `Uri` of the original resource that matches the resource which `Uri` is provided as an argument. + +You can combine this API with the [`registerTextDocumentContentProvider` method in the `workspace` namespace](/api/references/vscode-api#workspace), which lets you provide contents for arbitrary resources, given a `Uri`. + +## Next steps + +To learn more about VS Code extensibility model, try these topics: + +- [SCM API Reference](/api/references/vscode-api#scm) - Read the full SCM API documentation +- [Git Extension](https://github.com/Microsoft/vscode/tree/master/extensions/git) - Learn by reading the Git extension implementation +- [Extension API Overview](/api) - Learn about the full VS Code extensibility model. +- [Extension Manifest File](/api/references/extension-manifest) - VS Code package.json extension manifest file reference +- [Contribution Points](/api/references/contribution-points) - VS Code contribution points reference diff --git a/api/extension-guides/search-provider.md b/api/extension-guides/search-provider.md new file mode 100644 index 0000000000000000000000000000000000000000..2aef0678ce0865d74c9d891b8b6635512c893368 --- /dev/null +++ b/api/extension-guides/search-provider.md @@ -0,0 +1,8 @@ +--- +DateApproved: +MetaDescription: +--- + +# Search Provider + +Sample to be written. diff --git a/api/extension-guides/task-provider.md b/api/extension-guides/task-provider.md new file mode 100644 index 0000000000000000000000000000000000000000..e341646b6723eca3de9c8ed55571ae11d3ffb218 --- /dev/null +++ b/api/extension-guides/task-provider.md @@ -0,0 +1,101 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 49744351-83ef-4ef6-99e7-2485e6e9c79f +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Learn how to contribute tasks to Visual Studio Code through an extension (plug-in). +--- + +# Task Provider + +Users normally define [tasks](/docs/editor/tasks) in Visual Studio Code in a `tasks.json` file. However, there are some tasks during software development that can be automatically detected by VS Code. This topic describes how extensions can auto-detect and provide tasks to end-users. + +This guide teachs you how to build a Task Provider that auto-detects tasks defined in [Rakefiles](https://ruby.github.io/rake/). The complete source code is at: https://github.com/Microsoft/vscode-extension-samples/tree/master/task-provider-sample. + +## Task Definition + +To uniquely identify a task in the system, an extension contributing a task needs to define the properties that identify a task. In the Rake example, the task definition looks like this: + +```json +"taskDefinitions": [ + { + "type": "rake", + "required": [ + "task" + ], + "properties": { + "task": { + "type": "string", + "description": "The Rake task to customize" + }, + "file": { + "type": "string", + "description": "The Rake file that provides the task. Can be omitted." + } + } + } +] +``` + +This contributes a task definition for `rake` tasks. The task definition has two attributes `task` and `file`. `task` is the name of the Rake task and `file` points to the Rake file that contains the task. The `task` property is required, the `file` property is optional. If the `file` attribute is omitted, the rake file in the root of the workspace folder is used. + +## Task provider + +Analogous to language providers that let extensions support code completion, an extension can register a task provider to compute all available tasks. This is done using the `vscode.tasks` namespace as shown in the following code snippet: + +```ts +import * as vscode from 'vscode'; + +let rakePromise: Thenable | undefined = undefined; +const taskProvider = vscode.tasks.registerTaskProvider('rake', { + provideTasks: () => { + if (!rakePromise) { + rakePromise = getRakeTasks(); + } + return rakePromise; + }, + resolveTask(_task: vscode.Task): vscode.Task | undefined { + return undefined; + } +}); +``` + +The `resolveTask` method returns `undefined` and is currently not called by VS Code. It is there to optimize task loading in the future. + +The `getRakeTasks` implementation does the following: + +- Lists all rake tasks defined in a rake file using the `rake -AT -f Rakefile` command. +- Parses the stdio output. +- For every listed task, creates a `vscode.Task` implementation. + +Since a Rake task instantiation needs a task definition as defined in the `package.json` file, VS Code also defines the structure using a TypeScript interface like this: + +```typescript +interface RakeTaskDefinition extends vscode.TaskDefinition { + /** + * The task name + */ + task: string; + + /** + * The rake file containing the task + */ + file?: string; +} +``` + +Assuming that the output comes from a task called `compile`, the corresponding task creation then looks like this: + +```typescript +let task = new vscode.Task( + { type: 'rake', task: 'compile' }, + 'compile', + 'rake', + new vscode.ShellExecution('rake compile') +); +``` + +For every task listed in the output, a corresponding VS Code task is created using the above pattern and then returns the array of all tasks from the `getRakeTasks` call. + +The `ShellExecution` executes the `rake compile` command in the shell that is specific for the OS (for example under Windows the command would be executed in PowerShell, under Ubuntu in bash). If the task should directly execute a process (without spawning a shell), the `vscode.ProcessExecution` can be used. `ProcessExecution` has the advantage that the extension has full control over the arguments passed to the process. Using `ShellExecution` makes use of the shell command interpretation (like wildcard expanding under bash). If the `ShellExecution` is created with a single command line, then the extension needs to ensure proper quoting and escaping (for example to handle white spaces) inside the command. diff --git a/api/extension-guides/terminal.md b/api/extension-guides/terminal.md new file mode 100644 index 0000000000000000000000000000000000000000..782ab8e89946ac156439bb85f392e885ee5c9203 --- /dev/null +++ b/api/extension-guides/terminal.md @@ -0,0 +1,8 @@ +--- +DateApproved: +MetaDescription: +--- + +# Terminal Guide + +https://github.com/Microsoft/vscode-extension-samples/tree/master/terminal-sample diff --git a/api/extension-guides/tree-view.md b/api/extension-guides/tree-view.md new file mode 100644 index 0000000000000000000000000000000000000000..6f4bdcb76374842e27407141841b5464ca1686a9 --- /dev/null +++ b/api/extension-guides/tree-view.md @@ -0,0 +1,177 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 9b10cda2-4eb0-4989-8f82-23a46b96c1bb +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: A guide to using Tree View in Visual Studio Code extension (plug-in). +--- + +# Tree View Guide + +This guide teaches you how to write an extension that contributes view containers and tree views to Visual Studio Code. You can find a sample extension with source code at: https://github.com/Microsoft/vscode-extension-samples/tree/master/tree-view-sample. + +## View Container + +A View Container contains a list of views that is displayed next to the built-in View Containers. + +![View Container](images/tree-view/view-container.png) + +To contribute a View Container, you should first register it using [`contributes.viewsContainers`](/api/references/contribution-points#contributes.viewsContainers) Contribution Point in `package.json`. You have to specify following required fields: + +- `id`: The name of the new view container you're creating +- `title`: The name which will show up at the top of the view container +- `icon`: an image which will be displayed for the view container in the activity bar + +```json +"contributes": { + "viewsContainers": { + "activitybar": [ + { + "id": "package-explorer", + "title": "Package Explorer", + "icon": "media/dep.svg" + } + ] + } +} +``` + +## Tree View + +A view is an UI section that is shown inside the View Container. With the [`contributes.views`](/api/references/contribution-points#contributes.views) Contribution Point, you can add new views to the built-in or contributed View Containers. + +![View](images/tree-view/view.png) + +To contribute a view, you should first register it using [`contributes.views`](/api/references/vscode-api) Contribution Point in `package.json`. You must specify an identifier and name for the view, and you can contribute to following locations: + +- `explorer`: Explorer view in the Side Bar +- `debug`: Debug view in the Side Bar +- `scm`: Source Control view in the Side Bar +- `test`: Test explorer view in the Side Bar +- Contributed View Containers + +Example: + +```json +"contributes": { + "views": { + "package-explorer": [ + { + "id": "nodeDependencies", + "name": "Node Dependencies", + "when": "explorer" + } + ] + } +} +``` + +When the user opens the view, VS Code will then emit an activationEvent [`onView:${viewId}`](/api/references/activation-events#onView) (e.g. `onView:nodeDependencies` for the example above). You can also control the visibility of the view by providing the `when` context value. + +## View Actions + +You can contribute actions at the following locations in the view + +- `view/title`: Location to show actions in the view title. Primary or inline actions use `"group": "navigation"` and rest are secondary actions which are in `...` menu. +- `view/item/context`: Location to show actions for the tree item. Inline actions use `"group": "inline"` and rest are secondary actions which are in `...` menu. + +You can control the visibility of these actions using the `when` property. + +![View Actions](images/tree-view/view-actions.png) + +Examples: + +```json +"contributes": { + "commands": [ + { + "command": "nodeDependencies.refreshEntry", + "title": "Refresh", + "icon": { + "light": "resources/light/refresh.svg", + "dark": "resources/dark/refresh.svg" + } + }, + { + "command": "nodeDependencies.addEntry", + "title": "Add" + }, + { + "command": "nodeDependencies.editEntry", + "title": "Edit", + "icon": { + "light": "resources/light/edit.svg", + "dark": "resources/dark/edit.svg" + } + }, + { + "command": "nodeDependencies.deleteEntry", + "title": "Delete" + } + ], + "menus": { + "view/title": [ + { + "command": "nodeDependencies.refreshEntry", + "when": "view == nodeDependencies", + "group": "navigation" + }, + { + "command": "nodeDependencies.addEntry", + "when": "view == nodeDependencies" + } + ], + "view/item/context": [ + { + "command": "nodeDependencies.editEntry", + "when": "view == nodeDependencies && viewItem == dependency", + "group": "inline" + }, + { + "command": "nodeDependencies.deleteEntry", + "when": "view == nodeDependencies && viewItem == dependency" + } + ] + } +} +``` + +**Note:** If you want to show an action for specific items, you can do it by defining context of a tree item using `TreeItem.contextValue` and you can specify the context value for key `viewItem` in `when` expression. + +Examples: + +```json +"contributes": { + "menus": { + "view/item/context": [ + { + "command": "nodeDependencies.deleteEntry", + "when": "view == nodeDependencies && viewItem == dependency" + } + ] + } +} +``` + +## TreeDataProvider + +Extension writers should register a [`TreeDataProvider`](/api/references/vscode-api#TreeDataProvider) programmatically to populate data in the view. + +```typescript +vscode.window.registerTreeDataProvider('nodeDependencies', new DepNodeProvider()); +``` + +See [nodeDependencies.ts](https://github.com/Microsoft/vscode-extension-samples/tree/master/tree-view-sample/src/nodeDependencies.ts) for the implementation. + +## TreeView + +If you would like to perform some UI operations on the view programatically, you can use `window.createTreeView` instead of `window.registerTreeDataProvider`. This will give access to the view which you can use for performing view operations. + +```typescript +vscode.window.createTreeView('ftpExplorer', { + treeDataProvider: new FtpTreeDataProvider() +}); +``` + +See [ftpExplorer.ts](https://github.com/Microsoft/vscode-extension-samples/tree/master/tree-view-sample/src/ftpExplorer.ts) for the implementation. diff --git a/api/extension-guides/virtual-documents.md b/api/extension-guides/virtual-documents.md new file mode 100644 index 0000000000000000000000000000000000000000..3f4ad0b5faeaa3057f3557c762a4e07ab273485e --- /dev/null +++ b/api/extension-guides/virtual-documents.md @@ -0,0 +1,123 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 54fdcc33-7ad1-40cc-bc87-ded1841d01ad +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: A guide to using Virtual Documents in Visual Studio Code extensions (plug-ins) +--- + +# Virtual Documents + +The text document content provider API allows you to create readonly documents in Visual Studio Code from arbitrary sources. You can find a sample extension with source code at: https://github.com/Microsoft/vscode-extension-samples/blob/master/virtual-document-sample/README.md + +## TextDocumentContentProvider + +The API works by claiming an uri-scheme for which your provider then returns text contents. The scheme must be provided when registering a provider and cannot change afterwards. The same provider can be used for multiple schemes and multiple providers can be registered for a single scheme. + +```ts +vscode.workspace.registerTextDocumentContentProvider(myScheme, myProvider); +``` + +Calling `registerTextDocumentContentProvider` returns a disposable with which the registration can be undone. A provider must only implement the `provideTextDocumentContent`-function which is called with an uri and cancellation token. + +```ts +const myProvider = class implements vscode.TextDocumentContentProvider { + provideTextDocumentContent(uri: vscode.Uri): string { + // simply invoke cowsay, use uri-path as text + return cowsay.say({ text: uri.path }); + } +}; +``` + +Note how the provider doesn't create uris for virtual documents - its role is to **provide** contents given such an uri. In return, content providers are wired into the open document logic so that providers are always considered. + +This sample uses a 'cowsay'-command that crafts an uri which the editor should then show: + +```ts +vscode.commands.registerCommand('cowsay.say', async () => { + let what = await vscode.window.showInputBox({ placeHolder: 'cow say?' }); + if (what) { + let uri = vscode.Uri.parse('cowsay:' + what); + let doc = await vscode.workspace.openTextDocument(uri); // calls back into the provider + await vscode.window.showTextDocument(doc, { preview: false }); + } +}); +``` + +The command prompts for input, creates an uri of the `cowsay`-scheme, opens a document for the uri, and finally opens an editor for that document. In step 3, opening the document, the provider is being asked to provide contents for that uri. + +With this we have a fully functional text document content provider. The next sections describe how virtual documents can be updated and how UI commands can be registered for virtual documents. + +### Update Virtual Documents + +Depending on the scenario virtual documents might change. To support that, providers can implement a `onDidChange`-event. It must be fired for an uri and the editor will then ask for the new contents - assuming the document is still in use. + +The `vscode.Event`-type defines the contract for eventing in VS Code. The easiest way to implement an event is `vscode.EventEmitter`, like so: + +```ts +const myProvider = class implements vscode.TextDocumentContentProvider { + // emitter and its event + onDidChangeEmitter = new vscode.EventEmitter(); + onDidChange = this.onDidChangeEmitter.event; + + //... +}; +``` + +That's all what's needed to make VS code listen for changes of virtual document. The next section will add an editor action that uses the event emitter. + +### Add Editor Commands + +To illustrate above change-event and to get more cowsay, an editor action is needed that reverses what the cow just said. First we need a command that does that: + +```ts +// register a command that updates the current cowsay +subscriptions.push( + vscode.commands.registerCommand('cowsay.backwards', async () => { + if (!vscode.window.activeTextEditor) { + return; // no editor + } + let { document } = vscode.window.activeTextEditor; + if (document.uri.scheme !== myScheme) { + return; // not my scheme + } + // get path-components, reverse it, and create a new uri + let say = document.uri.path; + let newSay = say + .split('') + .reverse() + .join(''); + let newUri = document.uri.with({ path: newSay }); + await vscode.window.showTextDocument(newUri, { preview: false }); + }) +); +``` + +The snippet above checks that we have an active editor and that its document is one of our scheme. These checks are needed because commands are available (and executable) to everyone. Then the path-component of the uri is reversed and a new uri is created from it, last an editor is opened. + +To top things with an editor command a declarative part in `package.json` is needed. In the `contributes`-section add this config: + +```json +"menus": { + "editor/title": [ + { + "command": "cowsay.backwards", + "group": "navigation", + "when": "resourceScheme == cowsay" + } + ] +} +``` + +This references the `cowsay.backwards`-command that defined in the `contributes/commands`-section and says it should appear in the editor title menu (the toolbar in the upper right corner). Now, just that would mean the command always shows, for every editor. That's what the `when`-clause is used for - it describes what condition must be true to show the action. In this sample it states that the scheme of the document in the editor must be the `cowsay`-scheme. The configuration is then repeated for the `commandPalette`-menu - it shows all commands by default. + +![cowsay-bwd](images/virtual-documents/cowsay-bwd.png) + +### Events and Visibility + +Document providers are first class citizens in VS Code, their contents appears in regular text documents, they use the same infrastructure as files etc. However, that also means that "your" documents cannot hide, they will appear in `onDidOpenTextDocument` and `onDidCloseTextDocument`-events, they are part of `vscode.workspace.textDocuments` and more. The rule for everyone is check the `scheme` of documents and then decide if you want to do something with/for the document. + +### File System API + +If you need more flexibility and power take a look at the [`FileSystemProvider`](/api/references/vscode-api#FileSystemProvider) API. It allows to implement a full file system, having files, folders, binary data, file-deletion, creation and more. diff --git a/api/extension-guides/webview.md b/api/extension-guides/webview.md new file mode 100644 index 0000000000000000000000000000000000000000..867007c375f86b61b82318268760c56ac176b39d --- /dev/null +++ b/api/extension-guides/webview.md @@ -0,0 +1,964 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: adddd33e-2de6-4146-853b-34d0d7e6c1f1 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Use the Webview API to create fully customizable views within Visual Studio Code. +--- + +# Webview API + +The webview API allows extensions to create fully customizable views within Visual Studio Code. For example, the built-in Markdown extension uses webviews to render Markdown previews. Webviews can also be used to build complex user interfaces beyond what VS Code's native APIs support. + +Think of a webview as an `iframe` within VS Code that your extension controls. A webview can render almost any HTML content in this frame, and it communicates with extensions using message passing. This freedom makes webviews incredibly powerful, and opens up a whole new range of extension possibilities. + +## Links + +- [Webview Sample](https://github.com/Microsoft/vscode-extension-samples/blob/master/webview-sample/README.md) + +### VS Code API Usage + +- [`window.createWebviewPanel`](/api/references/vscode-api#window.createWebviewPanel) +- [`window.registerWebviewPanelSerializer`](/api/references/vscode-api#window.registerWebviewPanelSerializer) + +## Should I use a webview? + +Webviews are pretty amazing, but they should also be used sparingly and only when VS Code's native API is inadequate. Webviews are resource heavy and run in a separate context from normal extensions. A poorly designed webview can also easily feel out of place within VS Code. + +Before using a webview, please consider the following: + +- Does this functionality really need to live within VS Code? Would it be better as a separate application or website? + +- Is a webview the only way to implement your feature? Can you use the regular VS Code APIs instead? + +- Will your webview add enough user value to justify its high resource cost? + +Remember: Just because you can do something with webviews, doesn't mean you should. However, if you are confident that you need to use webviews, then this document is here to help. Let's get started. + +## Webviews API basics + +To explain the webview API, we are going to build a simple extension called **Cat Coding**. This extension will use a webview to show a gif of a cat writing some code (presumably in VS Code). As we work through the API, we'll continue adding functionality to the extension, including a counter that keeps track of how many lines of source code our cat has written and notifications that inform the user when the cat introduces a bug. + +Here's the `package.json` for the first version of the **Cat Coding** extension. You can find the complete code for the example app [here](https://github.com/Microsoft/vscode-extension-samples/blob/master/webview-sample/README.md). The first version of our extension [contributes a command](/api/references/contribution-points#contributes.commands) called `catCoding.start`. When a user invokes this command, we will show a simple webview with our cat in it. Users will be able to invoke this command from the **Command Palette** as **Cat Coding: Start new cat coding session** or even create a keybinding for it if they are so inclined. + +```json +{ + "name": "cat-coding", + "description": "Cat Coding", + "version": "0.0.1", + "publisher": "bierner", + "engines": { + "vscode": "^1.23.0" + }, + "activationEvents": ["onCommand:catCoding.start"], + "main": "./out/src/extension", + "contributes": { + "commands": [ + { + "command": "catCoding.start", + "title": "Start new cat coding session", + "category": "Cat Coding" + } + ] + }, + "scripts": { + "vscode:prepublish": "tsc -p ./", + "compile": "tsc -watch -p ./", + "postinstall": "node ./node_modules/vscode/bin/install" + }, + "dependencies": { + "vscode": "*" + }, + "devDependencies": { + "@types/node": "^9.4.6", + "typescript": "^2.8.3" + } +} +``` + +Now let's implement the `catCoding.start` command. In our extension's main file, we register the `catCoding.start` command and use it to show a basic webview: + +```ts +import * as vscode from 'vscode'; + +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + // Create and show a new webview + const panel = vscode.window.createWebviewPanel( + 'catCoding', // Identifies the type of the webview. Used internally + 'Cat Coding', // Title of the panel displayed to the user + vscode.ViewColumn.One, // Editor column to show the new webview panel in. + {} // Webview options. More on these later. + ); + }) + ); +} +``` + +The `vscode.window.createWebviewPanel` function creates and shows a webview in the editor. Here is what you see if you try running the `catCoding.start` command in its current state: + +![An empty webview](images/webview/basics-no_content.png) + +Our command opens a new webview panel with the correct title, but with no content! To add our cat to new panel, we also need to set the HTML content of the webview using `webview.html`: + +```ts +import * as vscode from 'vscode'; + +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + // Create and show panel + const panel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + {} + ); + + // And set its HTML content + panel.webview.html = getWebviewContent(); + }) + ); +} + +function getWebviewContent() { + return ` + + + + + Cat Coding + + + + +`; +} +``` + +If you run the command again, now the webview looks like this: + +![A webview with some HTML](images/webview/basics-html.png) + +Progress! + +`webview.html` should always be a complete HTML document. HTML fragments or malformed HTML may cause unexpected behavior. + +### Updating webview content + +`webview.html` can also update a webview's content after it has been created. Let's use this to make **Cat Coding** more dynamic by introducing a rotation of cats: + +```ts +import * as vscode from 'vscode'; + +const cats = { + 'Coding Cat': 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif', + 'Compiling Cat': 'https://media.giphy.com/media/mlvseq9yvZhba/giphy.gif' +}; + +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + const panel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + {} + ); + + let iteration = 0; + const updateWebview = () => { + const cat = iteration++ % 2 ? 'Compiling Cat' : 'Coding Cat'; + panel.title = cat; + panel.webview.html = getWebviewContent(cat); + }; + + // Set initial content + updateWebview(); + + // And schedule updates to the content every second + setInterval(updateWebview, 1000); + }) + ); +} + +function getWebviewContent(cat: keyof typeof cats) { + return ` + + + + + Cat Coding + + + + +`; +} +``` + +![Updating the webview content](images/webview/basics-update.gif) + +Setting `webview.html` replaces the entire webview content, similar to reloading an iframe. This is important to remember once you start using scripts in a webview, since it means that setting `webview.html` also resets the script's state. + +The example above also uses `webview.title` to change the title of the document displayed in the editor. Setting the title does not cause the webview to be reloaded. + +### Lifecycle + +Webview panels are owned by the extension that creates them. The extension must hold onto the webview returned from `createWebviewPanel`. If your extension loses this reference, it cannot regain access to that webview again, even though the webview will continue to show in VS Code. + +As with text editors, a user can also close a webview panel at any time. When a webview panel is closed by the user, the webview itself is destroyed. Attempting to use a destroyed webview throws an exception. This means that the example above using `setInterval` actually has an important bug: if the user closes the panel, `setInterval` will continue to fire, which will try to update `panel.webview.html`, which of course will throw an exception. Cats hate exceptions. Let's fix this! + +The `onDidDispose` event is fired when a webview is destroyed. We can use this event to cancel further updates and clean up the webview's resources: + +```ts +import * as vscode from 'vscode'; + +const cats = { + 'Coding Cat': 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif', + 'Compiling Cat': 'https://media.giphy.com/media/mlvseq9yvZhba/giphy.gif' +}; + +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + const panel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + {} + ); + + let iteration = 0; + const updateWebview = () => { + const cat = iteration++ % 2 ? 'Compiling Cat' : 'Coding Cat'; + panel.title = cat; + panel.webview.html = getWebviewContent(cat); + }; + + updateWebview(); + const interval = setInterval(updateWebview, 1000); + + panel.onDidDispose( + () => { + // When the panel is closed, cancel any future updates to the webview content + clearInterval(interval); + }, + null, + context.subscriptions + ); + }) + ); +} +``` + +Extensions can also programmatically close webviews by calling `dispose()` on them. If, for example, we wanted to restrict our cat's workday to five seconds: + +```ts +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + const panel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + {} + ); + + panel.webview.html = getWebviewContent(cats['Coding Cat']); + + // After 5sec, pragmatically close the webview panel + const timeout = setTimeout(() => panel.dispose(), 5000); + + panel.onDidDispose( + () => { + // Handle user closing panel before the 5sec have passed + clearTimeout(timeout); + }, + null, + context.subscriptions + ); + }) + ); +} +``` + +### Visibility and Moving + +When a webview panel is moved into a background tab, it becomes hidden. It is not destroyed however. VS Code will automatically restore the webview's content from `webview.html` when the panel is brought to the foreground again: + +![Webview content is automatically restored when the webview becomes visible again](images/webview/basics-restore.gif) + +The `.visible` property tells you if the webview panel is currently visible or not. + +Extensions can programmatically bring a webview panel to the foreground by calling `reveal()`. This method takes an optional target view column to show the panel in. A webview panel may only show in a single editor column at a time. Calling `reveal()` or dragging a webview panel to a new editor column moves the webview into that new column. + +![Webviews are moved when you drag them between tabs](images/webview/basics-drag.gif) + +Let's update our extension to only allow a single webview to exist at a time. If the panel is in the background, then the `catCoding.start` command will bring it to the foreground: + +```ts +export function activate(context: vscode.ExtensionContext) { + // Track currently webview panel + let currentPanel: vscode.WebviewPanel | undefined = undefined; + + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + const columnToShowIn = vscode.window.activeTextEditor + ? vscode.window.activeTextEditor.viewColumn + : undefined; + + if (currentPanel) { + // If we already have a panel, show it in the target column + currentPanel.reveal(columnToShowIn); + } else { + // Otherwise, create a new panel + currentPanel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + columnToShowIn, + {} + ); + currentPanel.webview.html = getWebviewContent(cats['Coding Cat']); + + // Reset when the current panel is closed + currentPanel.onDidDispose( + () => { + currentPanel = undefined; + }, + null, + context.subscriptions + ); + } + }) + ); +} +``` + +Here's the new extension in action: + +![Using a single panel and reveal](images/webview/basics-single_panel.gif) + +Whenever a webview's visibility changes, or when a webview is moved into a new column, the `onDidChangeViewState` event is fired. Our extension can use this event to change cats based on which column the webview is showing in: + +```ts +const cats = { + 'Coding Cat': 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif', + 'Compiling Cat': 'https://media.giphy.com/media/mlvseq9yvZhba/giphy.gif', + 'Testing Cat': 'https://media.giphy.com/media/3oriO0OEd9QIDdllqo/giphy.gif' +}; + +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + const panel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + {} + ); + panel.webview.html = getWebviewContent(cats['Coding Cat']); + + // Update contents based on view state changes + panel.onDidChangeViewState( + e => { + const panel = e.webviewPanel; + switch (panel.viewColumn) { + case vscode.ViewColumn.One: + updateWebviewForCat(panel, 'Coding Cat'); + return; + + case vscode.ViewColumn.Two: + updateWebviewForCat(panel, 'Compiling Cat'); + return; + + case vscode.ViewColumn.Three: + updateWebviewForCat(panel, 'Testing Cat'); + return; + } + }, + null, + context.subscriptions + ); + }) + ); +} + +function updateWebviewForCat(panel: vscode.WebviewPanel, catName: keyof typeof cats) { + panel.title = catName; + panel.webview.html = getWebviewContent(cats[catName]); +} +``` + +![Responding to onDidChangeViewState events](images/webview/basics-ondidchangeviewstate.gif) + +### Inspecting and debugging webviews + +The **Developer: Open Webview Developer Tools** VS Code command lets you debug webviews. Running the command launches an instance of Developer Tools for any currently visible webviews: + +![Webview Developer Tools](images/webview/basics-developer_tools.png) + +The contents of the webview are within an iframe inside the webview document. You can use Developer Tools to inspect and modify the webview's DOM, and debug scripts running within the webview itself. + +If you use the webview Developer Tools console, make sure to select the **active frame** environment from the drop-down in the top left corner of the Console panel: + +![Selecting the active frame](images/webview/debug-active-frame.png) + +The **active frame** environment is where the webview scripts themselves are executed. + +In addition, the **Developer: Reload Webview** command reloads all active webviews. This can be helpful if you need to reset a webview's state, or if some webview content on disk has changed and you want the new content to be loaded. + +## Loading local content + +Webviews run in isolated contexts that cannot directly access local resources. This is done for security reasons. This means that in order to load images, stylesheets, and other resources from your extension, or to load any content from the user's current workspace, you must use the `vscode-resource:` scheme inside the webview. + +The `vscode-resource:` scheme is similar to the `file:` scheme, but it only allows access to select local files. Like with `file:`, `vscode-resource:` loads a resource at a given absolute path from the disk. + +Imagine that we want to start bundling the cat gifs into our extension rather pulling them from Giphy. To do this, we first create a URI to the file on disk and then update this URI to use the `vscode-resource` scheme: + +```ts +import * as vscode from 'vscode'; +import * as path from 'path'; + +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + const panel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + {} + ); + + // Get path to resource on disk + const onDiskPath = vscode.Uri.file( + path.join(context.extensionPath, 'media', 'cat.gif') + ); + + // And get the special URI to use with the webview + const catGifSrc = onDiskPath.with({ scheme: 'vscode-resource' }); + + panel.webview.html = getWebviewContent(catGifSrc); + }) + ); +} +``` + +The value for `catGifSrc` will be something like: + +```bash +vscode-resource:/Users/toonces/projects/vscode-cat-coding/media/cat.gif +``` + +By default, `vscode-resource:` can only access resources in the following locations: + +- Within your extension's install directory. +- Within the user's currently active workspace. + +You can also always use data URIs to embed resources directly within the webview. + +### Controlling access to local resources + +Webviews can control which resources `vscode-resource:` can load using the `localResourceRoots` option. `localResourceRoots` defines a set of root URIs from which local content may be loaded. + +We can use `localResourceRoots` to restrict **Cat Coding** webviews to only load resources from a `media` directory in our extension: + +```ts +import * as vscode from 'vscode'; +import * as path from 'path'; + +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + const panel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + { + // Only allow the webview to access resources in our extension's media directory + localResourceRoots: [vscode.Uri.file(path.join(context.extensionPath, 'media'))] + } + ); + + const onDiskPath = vscode.Uri.file( + path.join(context.extensionPath, 'media', 'cat.gif') + ); + const catGifSrc = onDiskPath.with({ scheme: 'vscode-resource' }); + + panel.webview.html = getWebviewContent(catGifSrc); + }) + ); +} +``` + +To disallow all local resources, just set `localResourceRoots` to `[]`. + +In general, webviews should be as restrictive as possible in loading local resources. However, keep in mind that `vscode-resource` and `localResourceRoots` do not offer complete security protection on their own. Make sure your webview also follows [security best practices](#security), and strongly consider adding a [content security policy](#content-security-policy) to further restrict the content that can be loaded. + +### Theming webview content + +Webview can use CSS to change their appearance based on VS Code's current theme. VS Code groups themes into three categories, and adds a special class to the `body` element to indicate the current theme: + +- `vscode-light` - Light themes. +- `vscode-dark` - Dark themes. +- `vscode-high-contrast` - High contrast themes. + +The following CSS changes the text color of the webview based on the user's current theme: + +```css +body.vscode-light { + color: black; +} + +body.vscode-dark { + color: white; +} + +body.vscode-high-contrast { + color: red; +} +``` + +When developing a webview application, make sure that it works for the three types of themes. And always test your webview in high-contrast mode to make sure it will be usable by people with visual disabilities. + +Webviews can also access VS Code theme colors using [CSS variables](https://developer.mozilla.org/docs/Web/CSS/Using_CSS_variables). These variable names are prefixed with `vscode` and replace the `.` with `-`. For example `editor.foreground` becomes `var(--vscode-editor-foreground)`: + +```css +code { + color: var(--vscode-editor-foreground); +} +``` + +Review the [Theme Color Reference](/api/references/theme-color) for the available theme variables. + +The following font related variables are also defined: + +- `-vscode-editor-font-family` - Editor font family (from the `editor.fontFamily` setting). +- `-vscode-editor-font-weight` - Editor font size (from the `editor.fontWeight` setting). +- `-vscode-editor-font-size` - Editor font weight (from the `editor.fontWeight` setting). + +## Scripts and message passing + +Webviews are just like iframes, which means that they can also run scripts. JavaScript is disabled in webviews by default, but it can easily re-enable by passing in the `enableScripts: true` option. + +Let's use a script to add a counter tracking the lines of source code our cat has written. Running a basic script is pretty simple, but note that this example is only for demonstration purposes. In practice, your webview should always disable inline scripts using a [content security policy](#content-security-policy): + +```ts +import * as path from 'path'; +import * as vscode from 'vscode'; + +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + const panel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + { + // Enable scripts in the webview + enableScripts: true + } + ); + + panel.webview.html = getWebviewContent(); + }) + ); +} + +function getWebviewContent() { + return ` + + + + + Cat Coding + + + +

0

+ + + +`; +} +``` + +![A script running in a webview](images/webview/scripts-basic.gif) + +Wow! that's one productive cat. + +Webview scripts can do just about anything that a script on a normal webpage can. Keep in mind though that webviews exist in their own context, so scripts in a webview do not have access to the VS Code API. That's where message passing comes in! + +### Passing messages from an extension to a webview + +An extension can send data to its webviews using `webview.postMessage()`. This method sends any JSON serializable data to the webview. The message is received inside the webview through the standard `message` event. + +To demonstrate this, let's add a new command to **Cat Coding** that instructs the currently coding cat to refactor their code (thereby reducing the total number of lines). The new `catCoding.doRefactor` command use `postMessage` to send the instruction to the current webview, and `window.addEventListener('message', event => { ... })` inside the webview itself to handle the message: + +```ts +export function activate(context: vscode.ExtensionContext) { + // Only allow a single Cat Coder + let currentPanel: vscode.WebviewPanel | undefined = undefined; + + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + if (currentPanel) { + currentPanel.reveal(vscode.ViewColumn.One); + } else { + currentPanel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + { + enableScripts: true + } + ); + currentPanel.webview.html = getWebviewContent(); + currentPanel.onDidDispose( + () => { + currentPanel = undefined; + }, + undefined, + context.subscriptions + ); + } + }) + ); + + // Our new command + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.doRefactor', () => { + if (!currentPanel) { + return; + } + + // Send a message to our webview. + // You can send any JSON serializable data. + currentPanel.webview.postMessage({ command: 'refactor' }); + }) + ); +} + +function getWebviewContent() { + return ` + + + + + Cat Coding + + + +

0

+ + + +`; +} +``` + +![Passing messages to a webview](images/webview/scripts-extension_to_webview.gif) + +### Passing messages from a webview to an extension + +Webviews can also pass messages back to their extension. This is accomplished using a `postMessage` function on a special VS Code API object inside the webview. To access the VS Code API object, call `acquireVsCodeApi` inside the webview. This function can only be invoked once per session. You must hang onto the instance of the VS Code API returned by this method, and hand it out to any other functions that wish to use it. + +We can use the VS Code API and `postMessage` in our **Cat Coding** webview to alert the extension when our cat introduces a bug in their code: + +```js +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + const panel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + { + enableScripts: true + } + ); + + panel.webview.html = getWebviewContent(); + + // Handle messages from the webview + panel.webview.onDidReceiveMessage( + message => { + switch (message.command) { + case 'alert': + vscode.window.showErrorMessage(message.text); + return; + } + }, + undefined, + context.subscriptions + ); + }) + ); +} + +function getWebviewContent() { + return ` + + + + + Cat Coding + + + +

0

+ + + +`; +} +``` + +![Passing messages from the webview to the main extension](images/webview/scripts-webview_to_extension.gif) + +For security reasons, you must keep the VS Code API object private and make sure it is never leaked into the global state. + +## Security + +As with any webpage, when creating a webview you must follow some basic security best practices. + +### Limit capabilities + +A webview should have the minimum set of capabilities that it needs. For example, if your webview does not need to run scripts, do not set the `enableScripts: true`. If your webview does not need to load resources from the user's workspace, set `localResourceRoots` to `[vscode.Uri.file(extensionContext.extensionPath)]` or even `[]` to disallow access to all local resources. + +### Content security policy + +[Content security policies](https://developers.google.com/web/fundamentals/security/csp/) further restrict the content that can be loaded and executed in webviews. For example, a content security policy can make sure that only a whitelist of scripts can be run in the webview, or even tell the webview to only load images over `https`. + +To add a content security policy, put a `` directive at the top of the webview's `` + +```ts +function getWebviewContent() { + return ` + + + + + + + + + Cat Coding + + + ... + +`; +} +``` + +The policy `default-src 'none';` disallows all content. We can then turn back on the minimal amount of content that our extension needs to function. Here's a content security policy that allows loading local scripts and stylesheets, and loading images over `https`: + +```html + +``` + +This content security policy also implicitly disables inline scripts and styles. It is a best practice to extract all inline styles and scripts to external files so that they can be properly loaded without relaxing the content security policy. + +### Only load content over https + +If your webview allows loading external resources, it is strongly recommended that you only allow these resources to be loaded over `https` and not over http. The example content security policy above already does this by only allowing images to be loaded over `https:`. + +### Sanitize all user input + +Just as you would for a normal webpage, when constructing the HTML for a webview, you must sanitize all user input. Failing to properly sanitize input can allow content injections, which may open your users up to a security risk. + +Example values that must be sanitized: + +- File contents. +- File and folder paths. +- User and workspace settings. + +Consider using a helper library to construct your HTML strings, or at least ensure that all content from the user's workspace is properly sanitized. + +Never rely on sanitization alone for security. Make sure to follow the other security best practices, such as having a [content security policy](#content-security-policy) to minimize the impact of any potential content injections. + +## Persistence + +In the standard webview [lifecycle](#lifecycle), webviews are created by `createWebviewPanel` and destroyed when the user closes them or when `.dispose()` is called. The contents of webviews however are created when the webview becomes visible and destroyed when the webview is moved into the background. Any state inside the webview will be lost when the webview is moved to a background tab. + +The best way to solve this is to make your webview stateless. Use [message passing](#passing-messages-from-a-webview-to-an-extension) to save off the webview's state and then restore the state when the webview becomes visible again. + +### getState and setState + +Scripts running inside a webview can use the `getState` and `setState` methods to save off and restore a JSON serializable state object. This state is persisted even the webview content itself is destroyed when a webview panel becomes hidden. The state is destroyed when the webview panel is destroyed. + +```js +// Inside a webview script +const vscode = acquireVsCodeApi(); + +const counter = document.getElementById('lines-of-code-counter'); + +// Check if we have an old state to restore from +const previousState = vscode.getState(); +let count = previousState ? previousState.count : 0; +counter.textContent = count; + +setInterval(() => { + counter.textContent = count++; + // Update the saved state + vscode.setState({ count }); +}, 100); +``` + +`getState` and `setState` are the preferred way to persist state, as they have much lower performance overhead than `retainContextWhenHidden`. + +### Serialization + +By implementing a `WebviewPanelSerializer`, your webviews can be automatically restored when VS Code restarts. Serialization builds on `getState` and `setState`, and is only enabled if your extension registers a `WebviewPanelSerializer` for your webviews. + +To make our coding cats persist across VS Code restarts, first add a `onWebviewPanel` activation event to the extension's `package.json`: + +```json +"activationEvents": [ + ..., + "onWebviewPanel:catCoding" +] +``` + +This activation event ensures that our extension will be activated whenever VS Code needs to restore a webview with the viewType: `catCoding`. + +Then, in our extension's `activate` method, call `registerWebviewPanelSerializer` to register a new `WebviewPanelSerializer`. The `WebviewPanelSerializer` is responsible for restoring the contents of the webview from its persisted state. This state is the JSON blob that the webview contents set using `setState`. + +```ts +export function activate(context: vscode.ExtensionContext) { + // Normal setup... + + // And make sure we register a serializer for our webview type + vscode.window.registerWebviewPanelSerializer('catCoding', new CatCodingSerializer()); +} + +class CatCodingSerializer implements vscode.WebviewPanelSerializer { + async deserializeWebviewPanel(webviewPanel: vscode.WebviewPanel, state: any) { + // `state` is the state persisted using `setState` inside the webview + console.log(`Got state: ${state}`); + + // Restore the content of our webview. + // + // Make sure we hold on to the `webviewPanel` passed in here and + // also restore any event listeners we need on it. + webviewPanel.webview.html = getWebviewContent(); + } +} +``` + +Now if you restart VS Code with a cat coding panel open, the panel will be automatically restored in the same editor position. + +### retainContextWhenHidden + +For webviews with very complex UI or state that cannot be quickly saved and restored, you can instead use the `retainContextWhenHidden` option. This option makes a webview keep its content around but in a hidden state, even when the webview itself is no longer in the foreground. + +Although **Cat Coding** can hardly be said to have complex state, let's try enabling `retainContextWhenHidden` to see how the option changes a webview's behavior: + +```ts +import * as vscode from 'vscode'; + +export function activate(context: vscode.ExtensionContext) { + context.subscriptions.push( + vscode.commands.registerCommand('catCoding.start', () => { + const panel = vscode.window.createWebviewPanel( + 'catCoding', + 'Cat Coding', + vscode.ViewColumn.One, + { + enableScripts: true, + retainContextWhenHidden: true + } + ); + panel.webview.html = getWebviewContent(); + }) + ); +} + +function getWebviewContent() { + return ` + + + + + Cat Coding + + + +

0

+ + + +`; +} +``` + +![persistence retrain](images/webview/persistence-retrain.gif) + +Notice how the counter does not reset now when the webview is hidden and then restored. No extra code required! With `retainContextWhenHidden`, the webview acts similarly to a background tab in a web browser. Scripts and other dynamic content are suspended, but immediately resumed once the webview becomes visible again. You cannot send messages to a hidden webview, even when `retainContextWhenHidden` is enabled. + +Although `retainContextWhenHidden` may be appealing, keep in mind that this has high memory overhead and should only be used when other persistence techniques will not work. + +## Next steps + +If you'd like to learn more about VS Code extensibility, try these topics: + +- [Extension API](/api) - Learn about the full VS Code Extension API. +- [Extension Capabilities](/api/extension-capabilities/overview) - Take a look at other ways to extend VS Code. diff --git a/api/get-started/extension-anatomy.md b/api/get-started/extension-anatomy.md new file mode 100644 index 0000000000000000000000000000000000000000..5143fc4d77447e96f9ef4da8069d1c3c7ff32f93 --- /dev/null +++ b/api/get-started/extension-anatomy.md @@ -0,0 +1,135 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 8027f6fb-6c9e-4106-8ef1-f9b0ba1b7085 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Explain the structure of a Visual Studio Code extension (plug-in) +--- + +# Extension Anatomy + +In the last topic, you were able to get a basic extension running. How does it work under the hood? + +The `Hello World` extension does 3 things: + +- Registers the [`onCommand`](/api/references/activation-events#onCommand) [**Activation Event**](/api/references/activation-events): `onCommand:extension.helloWorld`, so the extension becomes activated when user runs the `Hello World` command. +- Uses the [`contributes.commands`](/api/references/contribution-points#contributes.commands) [**Contribution Point**](/api/references/contribution-points) to make the command `Hello World` available in the Command Palette, and bind it to a command ID `extension.helloWorld`. +- Uses the [`commands.registerCommand`](/api/references/vscode-api#commands.registerCommand) [**VS Code API**](/api/references/vscode-api) to bind a function to the registered command ID `extension.helloWorld`. + +Understanding these three concepts is crucial to writing extensions in VS Code: + +- [**Activation Events**](/api/references/activation-events): events upon which your extension becomes active. +- [**Contribution Points**](/api/references/contribution-points): static declarations that you make in the `package.json` [Extension Manifest](#extension-manifest) to extend VS Code. +- [**VS Code API**](/api/references/vscode-api): a set of JavaScript API that you can invoke in your extension code. + +In general, your extension would use a combination of Contribution Points and VS Code API to extend VS Code's functionality. The [Extension Capabilities Overview](/api/extension-capabilities/overview) topic helps you find the right Contribution Point and VS Code API for your extension. + +Let's take a closer look of `Hello World` sample's source code and see how these concepts apply to it. + +## Extension File Structure + +``` +. +├── .vscode +│ ├── launch.json // Config for launching and debugging the extension +│ └── tasks.json // Config for build task that compiles TypeScript +├── .gitignore // Ignore build output and node_modules +├── README.md // Readable description of your extension's functionality +├── src +│ └── extension.ts // Extension source code +├── package.json // Extension manifest +├── tsconfig.json // TypeScript configuration +``` + +You can read more about the configuration files: + +- `launch.json` used to configure VS Code [Debugging](/docs/editor/debugging) +- `tasks.json` for defining VS Code [Tasks](/docs/editor/tasks) +- `tsconfig.json` consult the TypeScript [Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) + +However, let's focus on `package.json` and `extensions.ts`, which are essential to understanding the `Hello World` extension. + +### Extension Manifest + +Each VS Code extension must have a `package.json` as its [Extension Manifest](/api/references/extension-manifest). The `package.json` contains a mix of Node.js fields such as `scripts` and `dependencies` and VS Code specific fields such as `publisher`, `activationEvents` and `contributes`. You can find description of all VS Code specific fields in [Extension Manifest Reference](/api/references/extension-manifest). Here are some most important fields: + +- `name` and `publisher`: VS Code uses `.` as a unique ID for the extension. For example, the Hello World sample has the ID `vscode-samples.helloworld-sample`. VS Code uses the ID to uniquely identify your extension +- `main`: The extension entry point. +- `activationEvents` and `contributes`: [Activation Events](/api/references/activation-events) and [Contribution Points](/api/references/contribution-points). +- `engines.vscode`: This specifies the minimum version of VS Code API that the extension depends on. +- The `postinstall` script: This would install the 1.25 version of VS Code API as specified in `engines.vscode`. Once the `vscode.d.ts` file is downloaded to `node_modules/vscode/vscode.d.ts`, you will get IntelliSense, jump to definition and error checking for all usage of VS Code API. + +```json +{ + "name": "helloworld-sample", + "displayName": "helloworld-sample", + "description": "HelloWorld example for VS Code", + "version": "0.0.1", + "publisher": "vscode-samples", + "repository": "https://github.com/Microsoft/vscode-extension-samples/helloworld-sample", + "engines": { + "vscode": "^1.31.0" + }, + "categories": ["Other"], + "activationEvents": ["onCommand:extension.helloWorld"], + "main": "./out/extension.js", + "contributes": { + "commands": [ + { + "command": "extension.helloWorld", + "title": "Hello World" + } + ] + }, + "scripts": { + "vscode:prepublish": "npm run compile", + "compile": "tsc -p ./", + "watch": "tsc -watch -p ./", + "postinstall": "node ./node_modules/vscode/bin/install", + "test": "npm run compile && node ./node_modules/vscode/bin/test" + }, + "devDependencies": { + "typescript": "^3.3.1", + "vscode": "^1.1.28", + "tslint": "^5.12.1", + "@types/node": "^10.12.21", + "@types/mocha": "^2.2.42" + } +} +``` + +## Extension Entry File + +The extension entry file exports two functions, `activate` and `deactivate`. `activate` is executed when your registered **Activation Event** happens. `deactivate` gives you a chance to clean up before your extension becomes deactivated. + +The [`vscode`](https://www.npmjs.com/package/vscode) module contains a script located at `node ./node_modules/vscode/bin/install`. The script pulls the VS Code API definition file depending on the `engines.vscode` field in `package.json`. After running the script, you would get IntelliSense, jump to definition and other TypeScript language features in your code. + +```ts +// The module 'vscode' contains the VS Code extensibility API +// Import the module and reference it with the alias vscode in your code below +import * as vscode from 'vscode'; + +// this method is called when your extension is activated +// your extension is activated the very first time the command is executed +export function activate(context: vscode.ExtensionContext) { + // Use the console to output diagnostic information (console.log) and errors (console.error) + // This line of code will only be executed once when your extension is activated + console.log('Congratulations, your extension "helloworld-sample" is now active!'); + + // The command has been defined in the package.json file + // Now provide the implementation of the command with registerCommand + // The commandId parameter must match the command field in package.json + let disposable = vscode.commands.registerCommand('extension.helloWorld', () => { + // The code you place here will be executed every time your command is executed + + // Display a message box to the user + vscode.window.showInformationMessage('Hello World!'); + }); + + context.subscriptions.push(disposable); +} + +// this method is called when your extension is deactivated +export function deactivate() {} +``` diff --git a/api/get-started/images/your-first-extension/debug.mp4 b/api/get-started/images/your-first-extension/debug.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..6c5a45519da5fa8fc7fa2e1e7eb43b2da2967b3a --- /dev/null +++ b/api/get-started/images/your-first-extension/debug.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6f8049c02c06561e684659bb34f370a43a0ff6c7e5d247f3cffd6380a1ac3646 +size 505351 diff --git a/api/get-started/images/your-first-extension/launch.mp4 b/api/get-started/images/your-first-extension/launch.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..cbd078b93ad42de6dc029ebf5ee076e46495d5b2 --- /dev/null +++ b/api/get-started/images/your-first-extension/launch.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:72354e0f8d3f36d99071f6fd753ebbe08c5f1dd837190434bb4432dd06d30a1f +size 225716 diff --git a/api/get-started/images/your-first-extension/reload.mp4 b/api/get-started/images/your-first-extension/reload.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..fce15733d37e48b07071adff6a3cbf0f3856e0a9 --- /dev/null +++ b/api/get-started/images/your-first-extension/reload.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:77f54ca12bfaa2f0d38c3c60edf7c49e821ff614f52075a3a99a0eabd6529f16 +size 315090 diff --git a/api/get-started/wrapping-up.md b/api/get-started/wrapping-up.md new file mode 100644 index 0000000000000000000000000000000000000000..90c12ceb6cfcde13a1e5f415011ae5fcdb577e08 --- /dev/null +++ b/api/get-started/wrapping-up.md @@ -0,0 +1,28 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: a15875fa-19b5-4c11-8903-864af133ce57 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Next steps to take after studying the Getting Started section +--- + +# Wrapping Up + +In the [Your First Extension](/api/get-started/your-first-extension) topic, you learned how to create, run and debug an extension. In the [Extension Anatomy](/api/get-started/extension-anatomy) topic, you learned fundamental concepts to Visual Studio Code extension development. However, we have only seen the tip of the iceberg, and here are some suggested routes for furthering your VS Code extension development skills. + +## Working with Extensions + +This section includes topics that help you develop high-quality VS Code extension. For example, you can learn + +- How to add [integration tests](/api/working-with-extensions/testing-extension) for your extension +- How to publish your extension to the [VS Code Marketplace](https://marketplace.visualstudio.com/) +- How to set up [Continuous Integration](/api/working-with-extensions/continuous-integration) for your extension + +## Extension Capabilities + +In this section, we split the [VS Code API](/api/references/vscode-api) and [Contribution Points](/api/references/contribution-points) into a few categories, each with short descriptions as to what your extension could achieve. Validate that your extension idea is achievable with VS Code API or look for new extension ideas here. + +## Guides & Samples + +We have a great collection of sample extensions that you can adapt from, and some of them include a detailed guide that explains the source code. You can find all Samples & Guides in the [Extension Guide Listing](/api/extension-guides/overview) or the [vscode-extension-samples](https://github.com/Microsoft/vscode-extension-samples) repository. diff --git a/api/get-started/your-first-extension.md b/api/get-started/your-first-extension.md new file mode 100644 index 0000000000000000000000000000000000000000..a8a2f4a49bbe8f6d75dfa746e97205eba3545398 --- /dev/null +++ b/api/get-started/your-first-extension.md @@ -0,0 +1,85 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: DC915D6C-13D4-4022-9101-57C4A4118B07 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Create your first Visual Studio Code extension (plug-in) with a simple Hello World example. +--- + +# Your First Extension + +In this topic, we'll teach you the fundamental concepts for building extensions. Make sure you have [Node.js](https://nodejs.org/en/) and [Git](https://git-scm.com/) installed, then install [Yeoman](http://yeoman.io/) and [VS Code Extension Generator](https://www.npmjs.com/package/generator-code) with: + +```bash +npm install -g yo generator-code +``` + +The generator scaffolds a project ready for development. Run the generator and fill out a few fields: + +```bash +yo code + +# ? What type of extension do you want to create? New Extension (TypeScript) +# ? What's the name of your extension? HelloWorld +### Press to choose default for all options below ### + +# ? What's the identifier of your extension? helloworld +# ? What's the description of your extension? LEAVE BLANK +# ? Enable stricter TypeScript checking in 'tsconfig.json'? Yes +# ? Setup linting using 'tslint'? Yes +# ? Initialize a git repository? Yes +# ? Which package manager to use? npm + +code ./helloworld +``` + +Then, inside the editor, press `kb(workbench.action.debug.start)`. This will compile and run the extension in a new **Extension Development Host** window. + +Run the `Hello World` command from the Command Palette (`kb(workbench.action.showCommands)`) in the new window: + + + +You should see the `Hello World` notification showing up. Success! + +## Developing the extension + +Let's make a change to the message: + +- Change the message from `Hello World` to `Hello VS Code` in `extension.ts` +- Run `Reload Window` in the new window +- Run the command `Hello World` again + +You should see the updated message showing up. + + + +Here are some ideas for you to try: + +- Give the `Hello World` command a new name in the Command Palette. +- [Contribute](/api/references/contribution-points) another command that displays current time in an information message. +- Replace the `vscode.window.showInformationMessage` with another [VS Code API](/api/references/vscode-api) call to show a warning message. + +## Debugging the extension + +VS Code's built-in debugging functionality makes it easy to debug extensions. Set a breakpoint by clicking the gutter next to a line, and VS Code will hit the breakpoint. You can hover over variables in the editor or use the Debug View in the left to check a variable's value. The Debug Console allows you to evaluate expressions. + + + +You can learn more about debugging Node.js apps in VS Code in the [Node.js Debugging Topic](/docs/nodejs/nodejs-debugging). + +## Next steps + +In the next topic, [Extension Anatomy](/api/get-started/extension-anatomy), we'll take a closer look at the source code of the `Hello World` sample and explain key concepts. + +You can find the source code of this tutorial at: https://github.com/Microsoft/vscode-extension-samples/tree/master/helloworld-sample. The [Extension Guides](/api/extension-guides/overview) topic contains other samples, each illustrating a different VS Code API or Contribution Point. + +### Using JavaScript + +In this guide, we mainly describe how to develop VS Code extension with TypeScript because we believe TypeScript offers the best experience for developing VS Code extensions. However, if you prefer JavaScript, you can still follow along using [helloworld-minimal-sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/helloworld-minimal-sample). diff --git a/api/index.md b/api/index.md new file mode 100644 index 0000000000000000000000000000000000000000..2e29d808a0150fe0854778bc7474d82049420b8f --- /dev/null +++ b/api/index.md @@ -0,0 +1,54 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: AD26EFB1-FFC6-4284-BAB8-F3BCB8294728 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Visual Studio Code has a rich extension API. Learn how to create your own extensions for VS Code. +--- + +# Extension API + +Visual Studio Code is built with extensibility in mind. From the UI to the editing experience, almost every part of VS Code can be customized and enhanced through the Extension API. In fact, many core features of VS Code are built as [extensions](https://github.com/Microsoft/vscode/tree/master/extensions) and use the same Extension API. + +This documentation describes: + +- How to build, run, debug, test and publish an extension +- How to take advantage of VS Code's rich Extension API +- Where to find guides and code samples to help get you started + +If you are looking for published extensions, head to the [VS Code Extension Marketplace](https://marketplace.visualstudio.com/vscode). + +## What can extensions do? + +Here are some examples of what you can achieve with the Extension API: + +- Change the look of VS Code with a color or icon theme - [Theming](/api/extension-capabilities/theming) +- Add custom components & views in the UI - [Extending the Workbench](/api/extension-capabilities/extending-workbench) +- Create a Webview to display a custom webpage built with HTML/CSS/JS - [Webview Guide](/api/extension-guides/webview) +- Support a new programming language - [Language Extensions Overview](/api/language-extensions/overview) +- Support debugging a specific runtime - [Debugger Extension Guide](/api/extension-guides/debugger-extension) + +If you'd like to have a more comprehensive overview of the Extension API, refer to the [Extension Capabilities Overview](/api/extension-capabilities/overview) page. [Extension Guides Overview](/api/extension-guides/overview) also includes a list of code samples and guides that illustrate various Extension API usage. + +## How to build extensions? + +Building a good extension can take a lot of effort. Here is how each section of the API doc can help you with: + +- **Get Started** teaches fundamental concepts for building extensions with the [Hello World](https://github.com/Microsoft/vscode-extension-samples/tree/master/helloworld-sample) sample. +- **Working with Extensions** includes in-depth guides on various extension development topics, such as [publishing](/api/working-with-extensions/publishing-extension) and [testing](/api/working-with-extensions/testing-extension) extensions. +- **Extension Capabilities** dissects VS Code's vast API into smaller categories and points you to more detailed topics. +- **Extension Guides** includes guides and code samples that explains specific usages of VS Code Extension API. +- **Language Extensions** illustrates how to add support for a programming language with guides and code samples. +- **Advanced Topics** explains advanced concepts such as [Extension Host](/api/advanced-topics/extension-host) and [Proposed API](/api/advanced-topics/using-proposed-api). +- **References** contains exhaustive references for the [VS Code API](/api/references/vscode-api), [Contribution Points](/api/references/contribution-points), and many other topics. + +## Looking for help + +If you have questions for extension development, try asking on: + +- [Stack Overflow](https://stackoverflow.com/questions/tagged/visual-studio-code): There are [12k questions](https://stackoverflow.com/questions/tagged/visual-studio-code) tagged `visual-studio-code`, and over half of them already have answers. Search for your issue, ask questions, or help your fellow developers by answering VS Code extension development questions! +- [Gitter Channel](https://gitter.im/Microsoft/vscode) and [VS Code Dev Slack](https://join.slack.com/t/vscode-dev-community/shared_invite/enQtMjIxOTgxNDE3NzM0LWU5M2ZiZDU1YjBlMzdlZjA2YjBjYzRhYTM5NTgzMTAxMjdiNWU0ZmQzYWI3MWU5N2Q1YjBiYmQ4MzY0NDE1MzY): Public chatroom for extension developers. Some VS Code team members chime in conversations. + +To provide feedback on the documentation, create new issues at [Microsoft/vscode-docs](https://github.com/Microsoft/vscode-docs/issues). +If you have extension questions that you cannot find an answer for, or issues with VS Code Extension API, please open new issues at [Microsoft/vscode](https://github.com/Microsoft/vscode/issues). diff --git a/api/language-extensions/embedded-languages.md b/api/language-extensions/embedded-languages.md new file mode 100644 index 0000000000000000000000000000000000000000..03c594be5d62f533a73f7bef063b62276bda6e70 --- /dev/null +++ b/api/language-extensions/embedded-languages.md @@ -0,0 +1,8 @@ +--- +DateApproved: +MetaDescription: +--- + +# Embedded Languages + +https://github.com/Microsoft/vscode/issues/47288 diff --git a/api/language-extensions/images/language-server-extension-guide/codeComplete.png b/api/language-extensions/images/language-server-extension-guide/codeComplete.png new file mode 100644 index 0000000000000000000000000000000000000000..fb1d30709a3868225b076a0283ef5e36865e72f2 Binary files /dev/null and b/api/language-extensions/images/language-server-extension-guide/codeComplete.png differ diff --git a/api/language-extensions/images/language-server-extension-guide/debugging-client.png b/api/language-extensions/images/language-server-extension-guide/debugging-client.png new file mode 100644 index 0000000000000000000000000000000000000000..63953a879ea7d94e87f7984d58251aaa2ef4eb0f --- /dev/null +++ b/api/language-extensions/images/language-server-extension-guide/debugging-client.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:36e52ae5df00019deba4d5786dddfb4780c729dbde7c03a19c668fd217af95b8 +size 314979 diff --git a/api/language-extensions/images/language-server-extension-guide/debugging-server.png b/api/language-extensions/images/language-server-extension-guide/debugging-server.png new file mode 100644 index 0000000000000000000000000000000000000000..d06e719036a5302b1afd2949ec7cb5f36251e881 --- /dev/null +++ b/api/language-extensions/images/language-server-extension-guide/debugging-server.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b1a27690b1e47aa75e056329ca75b75bab285cf8d3a9b9d8a4fed318662aee1f +size 315792 diff --git a/api/language-extensions/images/language-server-extension-guide/extensibility-architecture.png b/api/language-extensions/images/language-server-extension-guide/extensibility-architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..b94274d5bf421a013bab25d9b4008c8842c6ee52 Binary files /dev/null and b/api/language-extensions/images/language-server-extension-guide/extensibility-architecture.png differ diff --git a/api/language-extensions/images/language-server-extension-guide/lsp-illustration.png b/api/language-extensions/images/language-server-extension-guide/lsp-illustration.png new file mode 100644 index 0000000000000000000000000000000000000000..66aabf5711d3659685b7008d5550ea79fb8a5a16 Binary files /dev/null and b/api/language-extensions/images/language-server-extension-guide/lsp-illustration.png differ diff --git a/api/language-extensions/images/language-server-extension-guide/lsp-inspector.png b/api/language-extensions/images/language-server-extension-guide/lsp-inspector.png new file mode 100644 index 0000000000000000000000000000000000000000..c562b08014616d251a727953959f386b9de29e06 --- /dev/null +++ b/api/language-extensions/images/language-server-extension-guide/lsp-inspector.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ffab57aab93a48e578145e8db26a9288d00ffdd902d9206c6cfd9b07e80776c1 +size 225342 diff --git a/api/language-extensions/images/language-server-extension-guide/lsp-languages-editors.png b/api/language-extensions/images/language-server-extension-guide/lsp-languages-editors.png new file mode 100644 index 0000000000000000000000000000000000000000..0b234d45855a52313bc38684c1ef119f7cec9c8e Binary files /dev/null and b/api/language-extensions/images/language-server-extension-guide/lsp-languages-editors.png differ diff --git a/api/language-extensions/images/language-server-extension-guide/lsp-log.png b/api/language-extensions/images/language-server-extension-guide/lsp-log.png new file mode 100644 index 0000000000000000000000000000000000000000..544782312e0b1cb39efcd8b2a6742523696be921 --- /dev/null +++ b/api/language-extensions/images/language-server-extension-guide/lsp-log.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2e68101cb33b8e7963c75cfc574b0442a33ba4cfd65d88e761e9e9ab5f2f730c +size 109768 diff --git a/api/language-extensions/images/language-server-extension-guide/validation.png b/api/language-extensions/images/language-server-extension-guide/validation.png new file mode 100644 index 0000000000000000000000000000000000000000..ce9a541983f41b4fb1e40a9e1980fe8c7a255be3 Binary files /dev/null and b/api/language-extensions/images/language-server-extension-guide/validation.png differ diff --git a/api/language-extensions/images/language-server-extension-guide/validationOneProblem.png b/api/language-extensions/images/language-server-extension-guide/validationOneProblem.png new file mode 100644 index 0000000000000000000000000000000000000000..3bcffd90f3aafba8451608ded9fe89c9cddc0408 Binary files /dev/null and b/api/language-extensions/images/language-server-extension-guide/validationOneProblem.png differ diff --git a/api/language-extensions/images/language-support/code-completion.gif b/api/language-extensions/images/language-support/code-completion.gif new file mode 100644 index 0000000000000000000000000000000000000000..fcb4c3a7031daf40cc0660a30ac6a8f19cdcd39a --- /dev/null +++ b/api/language-extensions/images/language-support/code-completion.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bbc9ec3bd2090ba3e8ce5b643c6790ef6c192922a3a0ea6ea95e98582bfb0162 +size 351034 diff --git a/api/language-extensions/images/language-support/code-lens copy.gif b/api/language-extensions/images/language-support/code-lens copy.gif new file mode 100644 index 0000000000000000000000000000000000000000..ef2131e356f61712be31eee4d7fbaf7033fcfab7 --- /dev/null +++ b/api/language-extensions/images/language-support/code-lens copy.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d3b316b1d4d304a9ab96ac71119e9ca5207c1415b24e22be0b513b9b584c367c +size 1129232 diff --git a/api/language-extensions/images/language-support/code-lens.gif b/api/language-extensions/images/language-support/code-lens.gif new file mode 100644 index 0000000000000000000000000000000000000000..ef2131e356f61712be31eee4d7fbaf7033fcfab7 --- /dev/null +++ b/api/language-extensions/images/language-support/code-lens.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d3b316b1d4d304a9ab96ac71119e9ca5207c1415b24e22be0b513b9b584c367c +size 1129232 diff --git a/api/language-extensions/images/language-support/color-decorators.png b/api/language-extensions/images/language-support/color-decorators.png new file mode 100644 index 0000000000000000000000000000000000000000..fc1f008376c86871367a02c8a6547f4bd6a7cd51 Binary files /dev/null and b/api/language-extensions/images/language-support/color-decorators.png differ diff --git a/api/language-extensions/images/language-support/diagnostics.gif b/api/language-extensions/images/language-support/diagnostics.gif new file mode 100644 index 0000000000000000000000000000000000000000..11d65c86547db6e58a902b340803336eddb936ad Binary files /dev/null and b/api/language-extensions/images/language-support/diagnostics.gif differ diff --git a/api/language-extensions/images/language-support/document-highlights.gif b/api/language-extensions/images/language-support/document-highlights.gif new file mode 100644 index 0000000000000000000000000000000000000000..c759fc14683b1e1d14ff9b291ee0fb7dc6216419 --- /dev/null +++ b/api/language-extensions/images/language-support/document-highlights.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0680448e97a5a9e43c6a7c9f282ad2a28fdf0610a5364bcb36a1d8460fb89aea +size 114544 diff --git a/api/language-extensions/images/language-support/document-symbols.gif b/api/language-extensions/images/language-support/document-symbols.gif new file mode 100644 index 0000000000000000000000000000000000000000..327a1bd6756f215221762c35adc43cfac6fbcfa4 --- /dev/null +++ b/api/language-extensions/images/language-support/document-symbols.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:24af794e0aa70a4e679ef20ec3043113cde877db1e24b61e1bd591540a0b8b1e +size 687724 diff --git a/api/language-extensions/images/language-support/find-references.gif b/api/language-extensions/images/language-support/find-references.gif new file mode 100644 index 0000000000000000000000000000000000000000..413affc63e212d783b80ed242355906ec38a654e --- /dev/null +++ b/api/language-extensions/images/language-support/find-references.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3f05d4f34cfffaee608f5e43c2673a3ca64cdb5b7b2b5ae6dbd33ec6516bae7f +size 491626 diff --git a/api/language-extensions/images/language-support/format-document-range.gif b/api/language-extensions/images/language-support/format-document-range.gif new file mode 100644 index 0000000000000000000000000000000000000000..a70147e3c71495a505ec1b4792ec5d0616ff0ea2 --- /dev/null +++ b/api/language-extensions/images/language-support/format-document-range.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:50cfb552fe9dd911513bb7b5eec88663ffb80924a6248d90977adb7d9ac17aa5 +size 421575 diff --git a/api/language-extensions/images/language-support/format-document.gif b/api/language-extensions/images/language-support/format-document.gif new file mode 100644 index 0000000000000000000000000000000000000000..58dd474c2553b073fd7b323c85abba4a76aa7bbf --- /dev/null +++ b/api/language-extensions/images/language-support/format-document.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3cc74718d3bd1b4e62017791886c668bc149809c471c67572d103d165e7c0771 +size 210381 diff --git a/api/language-extensions/images/language-support/format-on-type.gif b/api/language-extensions/images/language-support/format-on-type.gif new file mode 100644 index 0000000000000000000000000000000000000000..546bddd4d3085d42ac7c0a94339e4747a76751d7 Binary files /dev/null and b/api/language-extensions/images/language-support/format-on-type.gif differ diff --git a/api/language-extensions/images/language-support/goto-definition.gif b/api/language-extensions/images/language-support/goto-definition.gif new file mode 100644 index 0000000000000000000000000000000000000000..5c4d3655cbfb7bc84ecd370f191a202a209eceef --- /dev/null +++ b/api/language-extensions/images/language-support/goto-definition.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:258c8a88e659af2c2ebfc30a9d8cb5e62d34441b1c700c0db811ebd051579f51 +size 201040 diff --git a/api/language-extensions/images/language-support/hovers.gif b/api/language-extensions/images/language-support/hovers.gif new file mode 100644 index 0000000000000000000000000000000000000000..ef76ab98471843c63762c2316f8b951563391086 --- /dev/null +++ b/api/language-extensions/images/language-support/hovers.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7a29e16ecb8c22ce8c5dd6ffc2a5bb0566219a6de44b2406f031a946809772c8 +size 156868 diff --git a/api/language-extensions/images/language-support/quick-fixes.gif b/api/language-extensions/images/language-support/quick-fixes.gif new file mode 100644 index 0000000000000000000000000000000000000000..e83b5b4b47143e4a0a894b813a09a85e1fd7598f --- /dev/null +++ b/api/language-extensions/images/language-support/quick-fixes.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2107803e03cf863b32754ecf48d7d1a69379ff7dcc694ff3e2c8561305c1d154 +size 152650 diff --git a/api/language-extensions/images/language-support/rename.gif b/api/language-extensions/images/language-support/rename.gif new file mode 100644 index 0000000000000000000000000000000000000000..e420b4c6eaa323d8a0c4b2ba5285dccaf96a4177 --- /dev/null +++ b/api/language-extensions/images/language-support/rename.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c56959054670a76484ad3b7a254a70bfcf889531aba7a2359e3b6182bd0ec3a5 +size 459464 diff --git a/api/language-extensions/images/language-support/signature-help.gif b/api/language-extensions/images/language-support/signature-help.gif new file mode 100644 index 0000000000000000000000000000000000000000..0f8ed4f5102da2e89662795a4aed42b375907a93 Binary files /dev/null and b/api/language-extensions/images/language-support/signature-help.gif differ diff --git a/api/language-extensions/images/language-support/smart-editing.gif b/api/language-extensions/images/language-support/smart-editing.gif new file mode 100644 index 0000000000000000000000000000000000000000..16f6783e3d4a2841395128b94bfefb004d418efb Binary files /dev/null and b/api/language-extensions/images/language-support/smart-editing.gif differ diff --git a/api/language-extensions/images/language-support/snippets.gif b/api/language-extensions/images/language-support/snippets.gif new file mode 100644 index 0000000000000000000000000000000000000000..9e40f330808ec713f0ce94d34608531952461d79 Binary files /dev/null and b/api/language-extensions/images/language-support/snippets.gif differ diff --git a/api/language-extensions/images/language-support/syntax-highlighting.png b/api/language-extensions/images/language-support/syntax-highlighting.png new file mode 100644 index 0000000000000000000000000000000000000000..c03bab9cfd8770047c6c9b7a0d8de8529444ce29 Binary files /dev/null and b/api/language-extensions/images/language-support/syntax-highlighting.png differ diff --git a/api/language-extensions/images/language-support/workspace-symbols.gif b/api/language-extensions/images/language-support/workspace-symbols.gif new file mode 100644 index 0000000000000000000000000000000000000000..603a4c8564e4911142ad69500f4bd57fe03bf538 --- /dev/null +++ b/api/language-extensions/images/language-support/workspace-symbols.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:003adf45c70db68908a1d7d8a2b49d7dc13801c1809b3391de2fe4f6ff72cdec +size 375100 diff --git a/api/language-extensions/images/overview/multi-editor.png b/api/language-extensions/images/overview/multi-editor.png new file mode 100644 index 0000000000000000000000000000000000000000..46b92e47764fa609a8e0f6ddfa327e8a2eab4677 Binary files /dev/null and b/api/language-extensions/images/overview/multi-editor.png differ diff --git a/api/language-extensions/images/overview/multi-ls.png b/api/language-extensions/images/overview/multi-ls.png new file mode 100644 index 0000000000000000000000000000000000000000..dba0b9f08d0cf22f9e2cc73a7008593ae43dce13 Binary files /dev/null and b/api/language-extensions/images/overview/multi-ls.png differ diff --git a/api/language-extensions/images/syntax-highlighting/generated-new-language-extension.png b/api/language-extensions/images/syntax-highlighting/generated-new-language-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..3fe0f4e439d5bbd7223bcdb9beddd661be8f992a Binary files /dev/null and b/api/language-extensions/images/syntax-highlighting/generated-new-language-extension.png differ diff --git a/api/language-extensions/images/syntax-highlighting/scope-inspector.png b/api/language-extensions/images/syntax-highlighting/scope-inspector.png new file mode 100644 index 0000000000000000000000000000000000000000..e2933a805f2639fdde5e04c782e09dbec67f95d2 Binary files /dev/null and b/api/language-extensions/images/syntax-highlighting/scope-inspector.png differ diff --git a/api/language-extensions/images/syntax-highlighting/scopes.png b/api/language-extensions/images/syntax-highlighting/scopes.png new file mode 100644 index 0000000000000000000000000000000000000000..54f8dc197686e012a6536595b4ae87d6e2449944 Binary files /dev/null and b/api/language-extensions/images/syntax-highlighting/scopes.png differ diff --git a/api/language-extensions/images/syntax-highlighting/yaml-grammar.png b/api/language-extensions/images/syntax-highlighting/yaml-grammar.png new file mode 100644 index 0000000000000000000000000000000000000000..ef4fe7597ad8ccf89a1ef20fb65aa8ff3e468d5e --- /dev/null +++ b/api/language-extensions/images/syntax-highlighting/yaml-grammar.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e5d3a414918efba2eeae65e956fe22d378f3b099344761829dc9418da771d7a2 +size 116600 diff --git a/api/language-extensions/images/syntax-highlighting/yo-convert.png b/api/language-extensions/images/syntax-highlighting/yo-convert.png new file mode 100644 index 0000000000000000000000000000000000000000..abd916fcb01a5d526e95c2cd395df7ffcdcd820b Binary files /dev/null and b/api/language-extensions/images/syntax-highlighting/yo-convert.png differ diff --git a/api/language-extensions/images/syntax-highlighting/yo-new-language-questions.png b/api/language-extensions/images/syntax-highlighting/yo-new-language-questions.png new file mode 100644 index 0000000000000000000000000000000000000000..63b82269ee54812c5a37edebce2cc249631e38d0 --- /dev/null +++ b/api/language-extensions/images/syntax-highlighting/yo-new-language-questions.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:72c9d7d40646507f560d5e4252df40d1961ea385e13c7753a2f09ea5f8472c68 +size 250566 diff --git a/api/language-extensions/images/syntax-highlighting/yo-new-language.png b/api/language-extensions/images/syntax-highlighting/yo-new-language.png new file mode 100644 index 0000000000000000000000000000000000000000..b2767d1b7d9591fb4861dc73351e7ca8eca6835b Binary files /dev/null and b/api/language-extensions/images/syntax-highlighting/yo-new-language.png differ diff --git a/api/language-extensions/language-configuration-guide.md b/api/language-extensions/language-configuration-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..353bf838133b620ffb7464076ab4271aeca3ebd2 --- /dev/null +++ b/api/language-extensions/language-configuration-guide.md @@ -0,0 +1,211 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: cd928e7f-bb5a-43b0-8e15-d398e416386d +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: A guide to configure language support for any language in Visual Studio Code. +--- + +# Language Configuration Guide + +The [`contributes.languages`](/api/references/contribution-points#contributes.languages) Contribution Point allows you to define a language configuration that controls the following Declarative Language Features: + +- Comment toggling +- Brackets definition +- Autoclosing +- Autosurrounding +- Folding +- Word pattern +- Indentation Rules + +Here is a [Language Configuration Sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/language-configuration-sample) that configures the editing experience for JavaScript files. This guide explains the content of `language-configuration.json`: + +**Note: If your language configuration file name is or ends with `language-configuration.json`, you will get auto-completion and validation in VS Code.** + +```json +{ + "comments": { + "lineComment": "//", + "blockComment": ["/*", "*/"] + }, + "brackets": [["{", "}"], ["[", "]"], ["(", ")"]], + "autoClosingPairs": [ + { "open": "{", "close": "}" }, + { "open": "[", "close": "]" }, + { "open": "(", "close": ")" }, + { "open": "'", "close": "'", "notIn": ["string", "comment"] }, + { "open": "\"", "close": "\"", "notIn": ["string"] }, + { "open": "`", "close": "`", "notIn": ["string", "comment"] }, + { "open": "/**", "close": " */", "notIn": ["string"] } + ], + "autoCloseBefore": ";:.,=}])>` \n\t", + "surroundingPairs": [ + ["{", "}"], + ["[", "]"], + ["(", ")"], + ["'", "'"], + ["\"", "\""], + ["`", "`"] + ], + "folding": { + "markers": { + "start": "^\\s*//\\s*#?region\\b", + "end": "^\\s*//\\s*#?endregion\\b" + } + }, + "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)", + "indentationRules": { + "increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$", + "decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\}\\]].*$" + } +} +``` + +## Comment toggling + +VS Code offers two commands for comment toggling. **Toggle Line Comment** and **Toggle Block Comment**. You can specify `comments.blockComment` and `comments.lineComment` to control how VS Code should comment out lines / blocks. + +```json +{ + "comments": { + "lineComment": "//", + "blockComment": ["/*", "*/"] + } +} +``` + +## Brackets definition + +When you move the cursor to a bracket defined here, VS Code will highlight that bracket together with its matching pair. + +```json +{ + "brackets": [["{", "}"], ["[", "]"], ["(", ")"]] +} +``` + +Moreover, when you run **Go to Bracket** or **Select to Bracket**, VS Code will use the definition above to find the nearest bracket and its matching pair. + +## Autoclosing + +When you type `'`, VS Code creates a pair of single quotes and puts your cursor in the middle: `'|'`. This section defines such pairs. + +```json +{ + "autoClosingPairs": [ + { "open": "{", "close": "}" }, + { "open": "[", "close": "]" }, + { "open": "(", "close": ")" }, + { "open": "'", "close": "'", "notIn": ["string", "comment"] }, + { "open": "\"", "close": "\"", "notIn": ["string"] }, + { "open": "`", "close": "`", "notIn": ["string", "comment"] }, + { "open": "/**", "close": " */", "notIn": ["string"] } + ] +} +``` + +The `notIn` key disables this feature in certain code ranges. For example, when you are writing the following code: + +```js +// ES6's Template String +`ES6's Template String`; +``` + +The single quote will not be autoclosed. + +Users can tweak the autoclosing behavior with the `editor.autoClosingQuotes` and `editor.autoClosingBrackets` settings. + +### Autoclosing before + +By default, VS Code only autocloses pairs if there is whitespace right after the cursor. So when you type `{` in the following JSX code, you would not get autoclose: + +```js +const Component = () => +
+ ^ Does not get autoclosed by default +
+``` + +However, this definition overrides that behavior: + +```json +{ + "autoCloseBefore": ";:.,=}])>` \n\t" +} +``` + +Now when you enter `{` right before `>`, VS Code autocloses it with `}`. + +## Autosurrounding + +When you select a range in VS Code and enter an opening bracket, VS Code surrounds the selected content with a pair of brackets. This feature is called Autosurrounding, and here you can define the autosurrounding pairs for a specific language: + +```json +{ + "surroundingPairs": [ + ["{", "}"], + ["[", "]"], + ["(", ")"], + ["'", "'"], + ["\"", "\""], + ["`", "`"] + ] +} +``` + +Users can tweak the autosurrounding behavior with the `editor.autoSurround` setting. + +## Folding + +In VS Code, there are three kinds of folding: + +- Indentation based folding: This is VS Code's default folding behavior. When it sees two lines of the same indentation level, it creates a folding marker that allows you to collapse that region. +- Language configuration folding: When VS Code finds both the `start` and `end` regex defined in `folding.markers`, it creates a folding marker enclosing the content inside the pair. The following JSON creates folding markers for `//#region` and `//#endregion`. + +```json +{ + "folding": { + "markers": { + "start": "^\\s*//\\s*#?region\\b", + "end": "^\\s*//\\s*#?endregion\\b" + } + } +} +``` + +- Language server folding: The Language Server responds to the [`textDocument/foldingRange`](https://microsoft.github.io/language-server-protocol/specification#textDocument_foldingRange) request with a list of folding ranges, and VS Code would render the ranges as folding markers. Learn more about the folding support in Language Server Protocol at the [Programmatic Language Feature](/api/language-extensions/programmatic-language-features) topic. + +## Word Pattern + +`wordPattern` defines what's considered as a word in the programming language. So when you use word related commands, like **Move cursor to word start** (`kb(cursorWordStartLeft)`) or **Move cursor to word end** (`kb(cursorWordEndRight)`)，the editor will use this regex to find the word boundaries. + +```json +{ + "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)" +} +``` + +## Indentation Rules + +`indentationRules` defines how the editor should adjust the indentation of current line or next line when you type, paste, and move lines. + +```json +{ + "indentationRules": { + "increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$", + "decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$" + } +} +``` + +For example, `if (true) {` matches `increasedIndentPattern`, then if you press `kbstyle(Enter)` after the open bracket `{`, the editor will automatically indent once, and your code will end up as: + +```javascript +if (true) { + console.log(); +``` + +If there is no indentation rule set for the programming language, the editor will indent when the line ends with an open bracket and outdent when you type an closing bracket. The _bracket_ here is defined by `brackets`. + +Notice that `editor.formatOnPaste` setting is controlled by the [`DocumentRangeFormattingEditProvider`](/api/references/vscode-api#DocumentRangeFormattingEditProvider) and not affected by auto indentation. diff --git a/api/language-extensions/language-server-extension-guide.md b/api/language-extensions/language-server-extension-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..2a531390207fa1154c70fe0731bdb076951f2f37 --- /dev/null +++ b/api/language-extensions/language-server-extension-guide.md @@ -0,0 +1,934 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: A8CBE8D6-1FEE-47BF-B81E-D79FA0DB5D03 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Learn how to create Language Servers to provide rich language features in Visual Studio Code. +--- + +# Language Server Extension Guide + +As you have seen in the [Programmatic Language Features](/api/language-extensions/programmatic-language-features) topic, it's possible to implement Language Features by directly using `languages.*` API. Language Server Extension, however, provides an alternative way of implementing such language support. + +This topic: + +- Explains the benefits of Language Server Extension. +- Walks you through building a Language Server using the [`Microsoft/vscode-languageserver-node`](https://github.com/Microsoft/vscode-languageserver-node) library. You can also jump directly to the code in [lsp-sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/lsp-sample). + +## Why Language Server? + +Language Server is a special kind of Visual Studio Code extension that powers the editing experience for many programming languages. With Language Servers, you can implement autocomplete, error-checking (diagnostics), jump-to-definition and many other [language features](/api/language-extensions/programmatic-language-features) supported in VS Code. + +However, while implementing support for language features in VS Code, we found three common problems: + +First, Language Servers are usually implemented in their native programming languages, and that presents a challenge in integrating them with VS Code which has a Node.js runtime. + +Additionally, language features can be resource intensive. For example, to correctly validate a file, Language Server needs to parse a large amount of files, build up Abstract Syntax Trees for them and perform static program analysis. Those operations could incur significant CPU and memory usage and we need to ensure that VS Code's performance remains unaffected. + +Finally, integrating multiple language toolings with multiple code editors could involve significant effort. From language toolings' perspective, they need to adapt to code editors with different APIs. From code editors' perspective, they cannot expect any uniform API from language toolings. This makes implementing language support for `M` languages in `N` code editors the work of `M * N`. + +To solve those problems, Microsoft specified [Language Server Protocol](https://microsoft.github.io/language-server-protocol) which standardizes the communication between language tooling and code editor. This way, Language Servers can be implemented in any language and run in its own process to avoid performance cost, as they communicate with the code editor through the Language Server Protocol. Furthermore, any LSP-compliant language toolings can integrate with multiple LSP-compliant code editors, and any LSP-compliant code editors can easily pickup multiple LSP-compliant language toolings. LSP is a win for both language tooling providers and code editor vendors! + +![LSP Languages and Editors](images/language-server-extension-guide/lsp-languages-editors.png) + +In this guide, we will: + +- Explain how to build a Language Server extension in VS Code using the provided [Node SDK](https://github.com/Microsoft/vscode-languageserver-node). +- Explain how to run, debug, log and test the Language Server extension. +- Point you to some advanced topics on Language Servers. + +## Implementing a Language Server + +### Overview + +In VS Code, a language server has two parts: + +- Language Client: A normal VS Code extension written in JavaScript / TypeScript. This extension has access to all [VS Code Namespace API](/api/references/vscode-api). +- Language Server: A language analysis tool running in a separate process. + +As briefly stated above there are two benefits of running the Language Server in a separate process: + +- The analysis tool can be implemented in any languages, as long as it can communicate with the Language Client following the Language Server Protocol. +- As language analysis tools are often heavy on CPU and Memory usage, running them in separate process avoids performance cost. + +Here is an illustration of VS Code running two Language Server extensions. The HTML Language Client and PHP Language Client are normal VS Code extensions written in TypeScript. Each of them instantiates a corresponding Language Server and communicates with them through LSP. Although the PHP Language Server is written in PHP, it can still communicate with the PHP Language Client through LSP. + +![LSP Illustration](images/language-server-extension-guide/lsp-illustration.png) + +This guide will teach you how to build a Language Client / Server using our [Node SDK](https://github.com/Microsoft/vscode-languageserver-node). The remaining document assumes that you are familiar with VS Code [Extension API](/api). + +### LSP Sample - A simple Language Server for plain text files + +Let's build a simple Language Server extension that implements autocomplete and diagnostics for plain text files. We will also cover the syncing of configurations between Client / Server. + +If you prefer to jump right into the code: + +- **[lsp-sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/lsp-sample)**: Heavily documented source code for this guide. +- **[lsp-multi-server-sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/lsp-multi-server-sample)**: A heavily documented, advanced version of **lsp-sample** that starts a different server instance per workspace folder to support the [multi-root workspace](/docs/editor/multi-root-workspaces) feature in VS Code. + +Clone the repository [Microsoft/vscode-extension-samples](https://github.com/Microsoft/vscode-extension-samples) and open the sample: + +```bash +> git clone https://github.com/Microsoft/vscode-extension-samples.git +> cd vscode-extension-samples/lsp-sample +> npm install +> npm run compile +> code . +``` + +The above installs all dependencies and opens the **lsp-sample** workspace containing both the client and server code. Here is a rough overview of the structure of **lsp-sample**: + +``` +. +├── client // Language Client +│ ├── src +│ │ ├── test // End to End tests for Language Client / Server +│ │ └── extension.ts // Language Client entry point +├── package.json // The extension manifest +└── server // Language Server + └── src + └── server.ts // Language Server entry point +``` + +### Explaining the 'Language Client' + +Let's first take a look at `/package.json`, which describes the capabilities of the Language Client. There are three interesting sections: + +First look the [`activationEvents`](/api/references/activation-events): + +```json +"activationEvents": [ + "onLanguage:plaintext" +] +``` + +This section tells VS Code to activate the extension as soon as a plain text file is opened (e.g. a file with the extension `.txt`). + +Next look at the [`configuration`](/api/references/contribution-points#contributes.configuration) section: + +```json +"configuration": { + "type": "object", + "title": "Example configuration", + "properties": { + "languageServerExample.maxNumberOfProblems": { + "scope": "resource", + "type": "number", + "default": 100, + "description": "Controls the maximum number of problems produced by the server." + } + } +} +``` + +This section contributes `configuration` settings to VS Code. The example will explain how these settings are sent over to the language server on startup and on every change of the settings. + +The actual Language Client code and the corresponding `package.json` is in the `/client` folder. The interesting part in the `/client/package.json` file is that it adds a dependency to the `vscode` extension host API and the `vscode-languageclient` library: + +```json +"dependencies": { + "vscode": "^1.1.18", + "vscode-languageclient": "^4.1.4" +} +``` + +As mentioned, the client is implemented as a normal VS Code extension, and it has access to all VS Code namespace API. + +Below is the content of the corresponding extension.ts file, which is the entry of the **lsp-sample** extension: + +```typescript +import * as path from 'path'; +import { workspace, ExtensionContext } from 'vscode'; + +import { + LanguageClient, + LanguageClientOptions, + ServerOptions, + TransportKind +} from 'vscode-languageclient'; + +let client: LanguageClient; + +export function activate(context: ExtensionContext) { + // The server is implemented in node + let serverModule = context.asAbsolutePath(path.join('server', 'out', 'server.js')); + // The debug options for the server + // --inspect=6009: runs the server in Node's Inspector mode so VS Code can attach to the server for debugging + let debugOptions = { execArgv: ['--nolazy', '--inspect=6009'] }; + + // If the extension is launched in debug mode then the debug server options are used + // Otherwise the run options are used + let serverOptions: ServerOptions = { + run: { module: serverModule, transport: TransportKind.ipc }, + debug: { + module: serverModule, + transport: TransportKind.ipc, + options: debugOptions + } + }; + + // Options to control the language client + let clientOptions: LanguageClientOptions = { + // Register the server for plain text documents + documentSelector: [{ scheme: 'file', language: 'plaintext' }], + synchronize: { + // Notify the server about file changes to '.clientrc files contained in the workspace + fileEvents: workspace.createFileSystemWatcher('**/.clientrc') + } + }; + + // Create the language client and start the client. + client = new LanguageClient( + 'languageServerExample', + 'Language Server Example', + serverOptions, + clientOptions + ); + + // Start the client. This will also launch the server + client.start(); +} + +export function deactivate(): Thenable { + if (!client) { + return undefined; + } + return client.stop(); +} +``` + +### Explaining the 'Language Server' + +> **Note:** The 'Server' implementation cloned from the GitHub repository has the final walkthrough implementation. To follow the walkthrough, you can create a new `server.ts` or modify the contents of the cloned version. + +In the example, the server is also implemented in TypeScript and executed using Node.js. Since VS Code already ships with a Node.js runtime, there is no need to provide your own, unless you have very specific requirements for the runtime. + +The source code for the Language Server is at `/server`. The interesting section in the server's `package.json` file is: + +```json +"dependencies": { + "vscode-languageserver": "^4.1.3" +} +``` + +This pulls in the `vscode-languageserver` library. + +Below is a server implementation that uses the provided simple text document manager which synchronizes text documents by always sending the file's full content from VS Code to the server. + +```typescript +import { + createConnection, + TextDocuments, + TextDocument, + Diagnostic, + DiagnosticSeverity, + ProposedFeatures, + InitializeParams, + DidChangeConfigurationNotification, + CompletionItem, + CompletionItemKind, + TextDocumentPositionParams +} from 'vscode-languageserver'; + +// Create a connection for the server. The connection uses Node's IPC as a transport. +// Also include all preview / proposed LSP features. +let connection = createConnection(ProposedFeatures.all); + +// Create a simple text document manager. The text document manager +// supports full document sync only +let documents: TextDocuments = new TextDocuments(); + +let hasConfigurationCapability: boolean = false; +let hasWorkspaceFolderCapability: boolean = false; +let hasDiagnosticRelatedInformationCapability: boolean = false; + +connection.onInitialize((params: InitializeParams) => { + let capabilities = params.capabilities; + + // Does the client support the `workspace/configuration` request? + // If not, we will fall back using global settings + hasConfigurationCapability = + capabilities.workspace && !!capabilities.workspace.configuration; + hasWorkspaceFolderCapability = + capabilities.workspace && !!capabilities.workspace.workspaceFolders; + hasDiagnosticRelatedInformationCapability = + capabilities.textDocument && + capabilities.textDocument.publishDiagnostics && + capabilities.textDocument.publishDiagnostics.relatedInformation; + + return { + capabilities: { + textDocumentSync: documents.syncKind, + // Tell the client that the server supports code completion + completionProvider: { + resolveProvider: true + } + } + }; +}); + +connection.onInitialized(() => { + if (hasConfigurationCapability) { + // Register for all configuration changes. + connection.client.register(DidChangeConfigurationNotification.type, undefined); + } + if (hasWorkspaceFolderCapability) { + connection.workspace.onDidChangeWorkspaceFolders(_event => { + connection.console.log('Workspace folder change event received.'); + }); + } +}); + +// The example settings +interface ExampleSettings { + maxNumberOfProblems: number; +} + +// The global settings, used when the `workspace/configuration` request is not supported by the client. +// Please note that this is not the case when using this server with the client provided in this example +// but could happen with other clients. +const defaultSettings: ExampleSettings = { maxNumberOfProblems: 1000 }; +let globalSettings: ExampleSettings = defaultSettings; + +// Cache the settings of all open documents +let documentSettings: Map> = new Map(); + +connection.onDidChangeConfiguration(change => { + if (hasConfigurationCapability) { + // Reset all cached document settings + documentSettings.clear(); + } else { + globalSettings = ( + (change.settings.languageServerExample || defaultSettings) + ); + } + + // Revalidate all open text documents + documents.all().forEach(validateTextDocument); +}); + +function getDocumentSettings(resource: string): Thenable { + if (!hasConfigurationCapability) { + return Promise.resolve(globalSettings); + } + let result = documentSettings.get(resource); + if (!result) { + result = connection.workspace.getConfiguration({ + scopeUri: resource, + section: 'languageServerExample' + }); + documentSettings.set(resource, result); + } + return result; +} + +// Only keep settings for open documents +documents.onDidClose(e => { + documentSettings.delete(e.document.uri); +}); + +// The content of a text document has changed. This event is emitted +// when the text document first opened or when its content has changed. +documents.onDidChangeContent(change => { + validateTextDocument(change.document); +}); + +async function validateTextDocument(textDocument: TextDocument): Promise { + // In this simple example we get the settings for every validate run. + let settings = await getDocumentSettings(textDocument.uri); + + // The validator creates diagnostics for all uppercase words length 2 and more + let text = textDocument.getText(); + let pattern = /\b[A-Z]{2,}\b/g; + let m: RegExpExecArray; + + let problems = 0; + let diagnostics: Diagnostic[] = []; + while ((m = pattern.exec(text)) && problems < settings.maxNumberOfProblems) { + problems++; + let diagnostic: Diagnostic = { + severity: DiagnosticSeverity.Warning, + range: { + start: textDocument.positionAt(m.index), + end: textDocument.positionAt(m.index + m[0].length) + }, + message: `${m[0]} is all uppercase.`, + source: 'ex' + }; + if (hasDiagnosticRelatedInformationCapability) { + diagnostic.relatedInformation = [ + { + location: { + uri: textDocument.uri, + range: Object.assign({}, diagnostic.range) + }, + message: 'Spelling matters' + }, + { + location: { + uri: textDocument.uri, + range: Object.assign({}, diagnostic.range) + }, + message: 'Particularly for names' + } + ]; + } + diagnostics.push(diagnostic); + } + + // Send the computed diagnostics to VS Code. + connection.sendDiagnostics({ uri: textDocument.uri, diagnostics }); +} + +connection.onDidChangeWatchedFiles(_change => { + // Monitored files have change in VS Code + connection.console.log('We received an file change event'); +}); + +// This handler provides the initial list of the completion items. +connection.onCompletion( + (_textDocumentPosition: TextDocumentPositionParams): CompletionItem[] => { + // The pass parameter contains the position of the text document in + // which code complete got requested. For the example we ignore this + // info and always provide the same completion items. + return [ + { + label: 'TypeScript', + kind: CompletionItemKind.Text, + data: 1 + }, + { + label: 'JavaScript', + kind: CompletionItemKind.Text, + data: 2 + } + ]; + } +); + +// This handler resolves additional information for the item selected in +// the completion list. +connection.onCompletionResolve( + (item: CompletionItem): CompletionItem => { + if (item.data === 1) { + item.detail = 'TypeScript details'; + item.documentation = 'TypeScript documentation'; + } else if (item.data === 2) { + item.detail = 'JavaScript details'; + item.documentation = 'JavaScript documentation'; + } + return item; + } +); + +/* +connection.onDidOpenTextDocument((params) => { + // A text document got opened in VS Code. + // params.uri uniquely identifies the document. For documents store on disk this is a file URI. + // params.text the initial full content of the document. + connection.console.log(`${params.textDocument.uri} opened.`); +}); +connection.onDidChangeTextDocument((params) => { + // The content of a text document did change in VS Code. + // params.uri uniquely identifies the document. + // params.contentChanges describe the content changes to the document. + connection.console.log(`${params.textDocument.uri} changed: ${JSON.stringify(params.contentChanges)}`); +}); +connection.onDidCloseTextDocument((params) => { + // A text document got closed in VS Code. + // params.uri uniquely identifies the document. + connection.console.log(`${params.textDocument.uri} closed.`); +}); +*/ + +// Make the text document manager listen on the connection +// for open, change and close text document events +documents.listen(connection); + +// Listen on the connection +connection.listen(); +``` + +### Adding a Simple Validation + +To add document validation to the server, we add a listener to the text document manager that gets called whenever the content of a text document changes. It is then up to the server to decide when the best time is to validate a document. In the example implementation, the server validates the plain text document and flags all occurrences of words that use ALL CAPS. The corresponding code snippet looks like this: + +```typescript +// The content of a text document has changed. This event is emitted +// when the text document first opened or when its content has changed. +documents.onDidChangeContent(async (change) => { + // In this simple example we get the settings for every validate run. + let settings = await getDocumentSettings(textDocument.uri); + + // The validator creates diagnostics for all uppercase words length 2 and more + let text = textDocument.getText(); + let pattern = /\b[A-Z]{2,}\b/g; + let m: RegExpExecArray; + + let problems = 0; + let diagnostics: Diagnostic[] = []; + while ((m = pattern.exec(text))) { + problems++; + let diagnostic: Diagnostic = { + severity: DiagnosticSeverity.Warning, + range: { + start: textDocument.positionAt(m.index), + end: textDocument.positionAt(m.index + m[0].length) + }, + message: `${m[0]} is all uppercase.`, + source: 'ex' + }; + if (hasDiagnosticRelatedInformationCapability) { + diagnostic.relatedInformation = [ + { + location: { + uri: textDocument.uri, + range: Object.assign({}, diagnostic.range) + }, + message: 'Spelling matters' + }, + { + location: { + uri: textDocument.uri, + range: Object.assign({}, diagnostic.range) + }, + message: 'Particularly for names' + } + ]; + } + diagnostics.push(diagnostic); + } + + // Send the computed diagnostics to VS Code. + connection.sendDiagnostics({ uri: textDocument.uri, diagnostics }); +} +``` + +### Diagnostics Tips and Tricks + +- If the start and end positions are the same, VS Code will underline with a squiggle the word at that position. +- If you want to underline with a squiggle until the end of the line, then set the character of the end position to Number.MAX_VALUE. + +To run the Language Server, do the following: + +- press `kb(workbench.action.tasks.build)` to start the build task. The task compiles both the client and the server. +- open the debug viewlet, select the `Launch Client` launch configuration and press the `Start Debugging` button to launch an additional `Extension Development Host` instance of VS Code that executes the extension code. +- Create a test.txt file in the root folder and paste the following content: + +```bash +TypeScript lets you write JavaScript the way you really want to. +TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. +ANY browser. ANY host. ANY OS. Open Source. +``` + +The `Extension Development Host` instance will then look like this: + +![Validating a text file](images/language-server-extension-guide/validation.png) + +### Debugging both Client and Server + +Debugging the client code is as easy as debugging a normal extension. Set a breakpoint in the client code and debug the extension by pressing `kb(workbench.action.debug.start)`. + +![Debugging the client](images/language-server-extension-guide/debugging-client.png) + +Since the server is started by the `LanguageClient` running in the extension (client), we need to attach a debugger to the running server. To do so, switch to the Debug view and select the launch configuration `Attach to Server` and press `kb(workbench.action.debug.start)`. This will attach the debugger to the server. + +![Debugging the server](images/language-server-extension-guide/debugging-server.png) + +### Logging Support for Language Server + +If you are using `vscode-languageclient` to implement the client, you can specify a setting `[langId].trace.server` that instructs the Client to log communications between Language Client / Server to a channel of the Language Client's `name`. + +For **lsp-sample**, you can set this setting: `"languageServerExample.trace.server": "verbose"`. Now head to the channel "Language Server Example". You should see the logs: + +![LSP Log](images/language-server-extension-guide/lsp-log.png) + +As Language Servers can be chatty (5 seconds of real-world usage can produce 5000 lines of log), we also provide a tool to visualize and filter the communication between Language Client / Server. You can save all logs from the channel into a file, and load that file with the [Language Server Protocol Inspector](https://github.com/Microsoft/language-server-protocol-inspector) at [https://microsoft.github.io/language-server-protocol/inspector](https://microsoft.github.io/language-server-protocol/inspector). + +![LSP Inspector](images/language-server-extension-guide/lsp-inspector.png) + +### Using Configuration Settings in the Server + +When writing the client part of the extension, we already defined a setting to control the maximum numbers of problems reported. We also wrote code on the server side to read these settings from the client: + +```typescript +function getDocumentSettings(resource: string): Thenable { + if (!hasConfigurationCapability) { + return Promise.resolve(globalSettings); + } + let result = documentSettings.get(resource); + if (!result) { + result = connection.workspace.getConfiguration({ + scopeUri: resource, + section: 'languageServerExample' + }); + documentSettings.set(resource, result); + } + return result; +} +``` + +The only thing we need to do now is to listen to configuration changes on the server side and if a settings changes, revalidate the open text documents. To be able to reuse the validate logic of the document change event handling, we extract the code into a `validateTextDocument` function and modify the code to honor a `maxNumberOfProblems` variable: + +```typescript +async function validateTextDocument(textDocument: TextDocument): Promise { + // In this simple example we get the settings for every validate run. + let settings = await getDocumentSettings(textDocument.uri); + + // The validator creates diagnostics for all uppercase words length 2 and more + let text = textDocument.getText(); + let pattern = /\b[A-Z]{2,}\b/g; + let m: RegExpExecArray; + + let problems = 0; + let diagnostics: Diagnostic[] = []; + while ((m = pattern.exec(text)) && problems < settings.maxNumberOfProblems) { + problems++; + let diagnostic: Diagnostic = { + severity: DiagnosticSeverity.Warning, + range: { + start: textDocument.positionAt(m.index), + end: textDocument.positionAt(m.index + m[0].length) + }, + message: `${m[0]} is all uppercase.`, + source: 'ex' + }; + if (hasDiagnosticRelatedInformationCapability) { + diagnostic.relatedInformation = [ + { + location: { + uri: textDocument.uri, + range: Object.assign({}, diagnostic.range) + }, + message: 'Spelling matters' + }, + { + location: { + uri: textDocument.uri, + range: Object.assign({}, diagnostic.range) + }, + message: 'Particularly for names' + } + ]; + } + diagnostics.push(diagnostic); + } + + // Send the computed diagnostics to VS Code. + connection.sendDiagnostics({ uri: textDocument.uri, diagnostics }); +} +``` + +The handling of the configuration change is done by adding a notification handler for configuration changes to the connection. The corresponding code looks like this: + +```typescript +connection.onDidChangeConfiguration(change => { + if (hasConfigurationCapability) { + // Reset all cached document settings + documentSettings.clear(); + } else { + globalSettings = ( + (change.settings.languageServerExample || defaultSettings) + ); + } + + // Revalidate all open text documents + documents.all().forEach(validateTextDocument); +}); +``` + +Starting the client again and changing the setting to maximum report 1 problem results in the following validation: + +![Maximum One Problem](images/language-server-extension-guide/validationOneProblem.png) + +### Adding additional Language Features + +The first interesting feature a language server usually implements is validation of documents. In that sense, even a linter counts as a language server and in VS Code linters are usually implemented as language servers (see [eslint](https://github.com/Microsoft/vscode-eslint) and [jshint](https://github.com/Microsoft/vscode-jshint) for examples). But there is more to language servers. They can provide code completion, Find All References or Go To Definition. The example code below adds code completion to the server. It proposes the two words 'TypeScript' and 'JavaScript'. + +```typescript +// This handler provides the initial list of the completion items. +connection.onCompletion( + (_textDocumentPosition: TextDocumentPositionParams): CompletionItem[] => { + // The pass parameter contains the position of the text document in + // which code complete got requested. For the example we ignore this + // info and always provide the same completion items. + return [ + { + label: 'TypeScript', + kind: CompletionItemKind.Text, + data: 1 + }, + { + label: 'JavaScript', + kind: CompletionItemKind.Text, + data: 2 + } + ]; + } +); + +// This handler resolves additional information for the item selected in +// the completion list. +connection.onCompletionResolve( + (item: CompletionItem): CompletionItem => { + if (item.data === 1) { + (item.detail = 'TypeScript details'), + (item.documentation = 'TypeScript documentation'); + } else if (item.data === 2) { + (item.detail = 'JavaScript details'), + (item.documentation = 'JavaScript documentation'); + } + return item; + } +); +``` + +The `data` fields is used to uniquely identify a completion item in the resolve handler. The data property is transparent for the protocol. Since the underlying message passing protocol is JSON based, the data field should only hold data that is serializable to and from JSON. + +All that is missing is to tell VS Code that the server supports code completion requests. To do so, flag the corresponding capability in the initialize handler: + +```typescript +connection.onInitialize((params): InitializeResult => { + ... + return { + capabilities: { + ... + // Tell the client that the server supports code completion + completionProvider: { + resolveProvider: true + } + } + }; +}); +``` + +The screen shot below shows the completed code running on a plain text file: + +![Code Complete](images/language-server-extension-guide/codeComplete.png) + +### Testing The Language Server + +To create a high-quality Language Server, we need to build a good test suite covering its functionalities. There are two common ways of testing Language Servers: + +- Unit Test: This is useful if you want to test specific functionalities in Language Servers by mocking up all the information being sent to it. VS Code's [HTML](https://github.com/Microsoft/vscode-html-languageservice) / [CSS](https://github.com/Microsoft/vscode-css-languageservice) / [JSON](https://github.com/Microsoft/vscode-json-languageservice) Language Servers take this approach to testing. The LSP npm modules itself use the approach. See [here](https://github.com/Microsoft/vscode-languageserver-node/blob/master/protocol/src/test/connection.test.ts) for some unit test written using the npm protocol module. +- End-to-End Test: This is similar to [VS Code extension test](/api/working-with-extensions/testing-extension). The benefit of this approach is that it runs the test by instantiating a VS Code instance with a workspace, opening the file, activating the Language Client / Server and running [VS Code commands](/api/references/commands). This approach is superior if you have files, settings or dependencies (such as `node_modules`) which are hard or impossible to mock. The popular [Python](https://github.com/Microsoft/vscode-python) extension takes this approach to testing. + +It is possible to do Unit Test in any testing framework of your choice. Here we describe how to do End-to-End testing for Language Server Extension. + +Open `.vscode/launch.json`, and you can find a `E2E` test target: + +```json +{ + "name": "Language Server E2E Test", + "type": "extensionHost", + "request": "launch", + "runtimeExecutable": "${execPath}", + "args": [ + "--extensionDevelopmentPath=${workspaceRoot}", + "--extensionTestsPath=${workspaceRoot}/client/out/test", + "${workspaceRoot}/client/testFixture" + ], + "stopOnEntry": false, + "sourceMaps": true, + "outFiles": ["${workspaceRoot}/client/out/test/**/*.js"] +} +``` + +If you run this debug target, it will launch a VS Code instance with `client/testFixture` as the active workspace. VS Code will then proceed to execute all tests in `client/src/test`. As a debugging tip, you can set breakpoints in TypeScript files in `client/src/test` and they will be hit. + +Let's take a look at the `completion.test.ts` file: + +```ts +import * as vscode from 'vscode'; +import * as assert from 'assert'; +import { getDocUri, activate } from './helper'; + +describe('Should do completion', () => { + const docUri = getDocUri('completion.txt'); + + it('Completes JS/TS in txt file', async () => { + await testCompletion(docUri, new vscode.Position(0, 0), { + items: [ + { label: 'JavaScript', kind: vscode.CompletionItemKind.Text }, + { label: 'TypeScript', kind: vscode.CompletionItemKind.Text } + ] + }); + }); +}); + +async function testCompletion( + docUri: vscode.Uri, + position: vscode.Position, + expectedCompletionList: vscode.CompletionList +) { + await activate(docUri); + + // Executing the command `vscode.executeCompletionItemProvider` to simulate triggering completion + const actualCompletionList = (await vscode.commands.executeCommand( + 'vscode.executeCompletionItemProvider', + docUri, + position + )) as vscode.CompletionList; + + assert.equal(actualCompletionList.items.length, expectedCompletionList.items.length); + expectedCompletionList.items.forEach((expectedItem, i) => { + const actualItem = actualCompletionList.items[i]; + assert.equal(actualItem.label, expectedItem.label); + assert.equal(actualItem.kind, expectedItem.kind); + }); +} +``` + +In this test, we: + +- Activate the extension. +- Run the command `vscode.executeCompletionItemProvider` with a URI and a position to simulate completion trigger. +- Assert the returned completion items against our expected completion items. + +Let's dive a bit deeper into the `activate(docURI)` function. It is defined in `client/src/test/helper.ts`: + +```ts +import * as vscode from 'vscode'; +import * as path from 'path'; + +export let doc: vscode.TextDocument; +export let editor: vscode.TextEditor; +export let documentEol: string; +export let platformEol: string; + +/** + * Activates the vscode.lsp-sample extension + */ +export async function activate(docUri: vscode.Uri) { + // The extensionId is `publisher.name` from package.json + const ext = vscode.extensions.getExtension('vscode.lsp-sample'); + await ext.activate(); + try { + doc = await vscode.workspace.openTextDocument(docUri); + editor = await vscode.window.showTextDocument(doc); + await sleep(2000); // Wait for server activation + } catch (e) { + console.error(e); + } +} + +async function sleep(ms: number) { + return new Promise(resolve => setTimeout(resolve, ms)); +} +``` + +In the activation part, we: + +- Get the extension using the `{publisher.name}.{extensionId}`, as defined in `package.json`. +- Open the specified document, and show it in the active text editor. +- Sleep for 2 seconds, so we are sure the Language Server is instantiated. + +After the preparation, we can run the [VS Code Commands](/api/references/commands) corresponding to each language feature, and assert against the returned result. + +There is one more test that covers the diagnostics feature that we just implemented. Check it out at `client/src/test/diagnostics.test.ts`. + +## Advanced Topics + +So far, this guide covered: + +- A brief overview of Language Server and Language Server Protocol. +- Architecture of a Language Server extension in VS Code +- The **lsp-sample** extension, and how to develop/debug/inspect/test it. + +There are some more advanced topics we could not fit in to this guide. We will include links to these resources for further studying of Language Server development. + +### Additional Language Server features + +The following language features are currently supported in a language server along with code completions: + +- _Document Highlights_: highlights all 'equal' symbols in a text document. +- _Hover_: provides hover information for a symbol selected in a text document. +- _Signature Help_: provides signature help for a symbol selected in a text document. +- _Goto Definition_: provides go to definition support for a symbol selected in a text document. +- _Goto Type Definition_: provides go to type/interface definition support for a symbol selected in a text document. +- _Goto Implementation_: provides go to implementation definition support for a symbol selected in a text document. +- _Find References_: finds all project-wide references for a symbol selected in a text document. +- _List Document Symbols_: lists all symbols defined in a text document. +- _List Workspace Symbols_: lists all project-wide symbols. +- _Code Actions_: compute commands to run (typically beautify/refactor) for a given text document and range. +- _CodeLens_: compute CodeLens statistics for a given text document. +- _Document Formatting_: this includes formatting of whole documents, document ranges and formatting on type. +- _Rename_: project-wide rename of a symbol. +- _Document Links_: compute and resolve links inside a document. +- _Document Colors_: compute and resolve colors inside a document to provide color picker in editor. + +The [Programatic Language Features](/api/language-extensions/programmatic-language-features) topic describes each of the language features above and provides guidance on how to implement them either through the language server protocol or by using the extensibility API directly from your extension. + +### Incremental Text Document Synchronization + +The example uses the simple text document manager provided by the `vscode-languageserver` module to synchronize documents between VS Code and the language server. + +This has two drawbacks: + +- Lots of data transfer since the whole content of a text document is sent to the server repeatedly. +- If an existing language library is used, such libraries usually support incremental document updates to avoid unnecessary parsing and abstract syntax tree creation. + +The protocol therefore supports incremental document synchronization as well. + +To make use of incremental document synchronization, a server needs to install three notification handlers: + +- _onDidOpenTextDocument_: is called when a text document is opened in VS Code. +- _onDidChangeTextDocument_: is called when the content of a text document changes in VS Code. +- _onDidCloseTextDocument_: is called when a text document is closed in VS Code. + +Below is a code snippet that illustrates how to hook these notification handlers on a connection and how to return the right capability on initialize: + +```typescript +connection.onInitialize((params): InitializeResult => { + ... + return { + capabilities: { + // Enable incremental document sync + textDocumentSync: TextDocumentSyncKind.Incremental, + ... + } + }; +}); + +connection.onDidOpenTextDocument((params) => { + // A text document was opened in VS Code. + // params.uri uniquely identifies the document. For documents stored on disk, this is a file URI. + // params.text the initial full content of the document. +}); + +connection.onDidChangeTextDocument((params) => { + // The content of a text document has change in VS Code. + // params.uri uniquely identifies the document. + // params.contentChanges describe the content changes to the document. +}); + +connection.onDidCloseTextDocument((params) => { + // A text document was closed in VS Code. + // params.uri uniquely identifies the document. +}); +``` + +### Using VS Code API directly to implement Language Features + +While Language Servers have many benefits, they are not the only option for extending the editing capabilities of VS Code. In the cases when you want to add some simple language features for a type of document, consider using `vscode.languages.register[LANGUAGE_FEATURE]Provider` as an option. + +Here is a [`completions-sample`](https://github.com/Microsoft/vscode-extension-samples/tree/master/completions-sample) using `vscode.languages.registerCompletionItemProvider` to add a few snippets as completions for plain text files. + +More samples illustrating the usage of VS Code API can be found at [https://github.com/Microsoft/vscode-extension-samples](https://github.com/Microsoft/vscode-extension-samples). + +### Error Tolerant Parser for Language Server + +Most of the time, the code in the editor is incomplete and syntactically incorrect, but developers would still expect autocomplete and other language features to work. Therefore, an error tolerant parser is necessary for a Language Server: The parser generates meaningful AST from partially complete code, and the Language Server provides language features based on the AST. + +When we were improving PHP support in VS Code, we realized the official PHP parser is not error tolerant and cannot be reused directly in the Language Server. Therefore, we worked on [Microsoft/tolerant-php-parser](https://github.com/Microsoft/tolerant-php-parser) and left detailed [notes](https://github.com/Microsoft/tolerant-php-parser/blob/master/docs/HowItWorks.md) that might help Language Server authors who need to implement an error tolerant parser. + +## Common questions + +### When I try to attach to the server, I get "cannot connect to runtime process (timeout after 5000ms)"? + +You will see this timeout error if the server isn't running when you try to attach the debugger. The client starts the language server so make sure you have started the client in order to have a running server. You may also need to disable your client breakpoints if they are interfering with starting the server. + +### I have read through this guide and the [LSP Specification](https://microsoft.github.io/language-server-protocol/), but I still have unresolved questions. Where can I get help? + +Please open an issue at https://github.com/Microsoft/language-server-protocol. diff --git a/api/language-extensions/multiroot-support.md b/api/language-extensions/multiroot-support.md new file mode 100644 index 0000000000000000000000000000000000000000..79faae25493ee5519f1524eb6af41c7a908067f5 --- /dev/null +++ b/api/language-extensions/multiroot-support.md @@ -0,0 +1,8 @@ +--- +DateApproved: +MetaDescription: +--- + +# Multiroot Support + +https://github.com/Microsoft/vscode/wiki/Extension-Authoring:-Adopting-Multi-Root-Workspace-APIs diff --git a/api/language-extensions/overview.md b/api/language-extensions/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..97908d0bfb62041b50a0ee8292020848a522822a --- /dev/null +++ b/api/language-extensions/overview.md @@ -0,0 +1,72 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 8b70dba5-f71d-46dd-8da1-f5d44b9a6a96 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Learn how to write a Language Extension (plug-in) to add support for a programming language in Visual Studio Code. +--- + +# Language Extensions Overview + +Visual Studio Code provides smart editing features for different programming languages through Language Extensions. VS Code doesn't provide built-in language support but offers a set of APIs that enable rich language features. For example, it is a bundled [HTML](https://github.com/Microsoft/vscode/tree/master/extensions/html) extension that allows VS Code to show syntax highlighting for HTML files. Similarly, when you type `console.` and `log` shows up in IntelliSense, it is the [Typescript Language Features](https://github.com/Microsoft/vscode/tree/master/extensions/typescript-language-features) extension at work. + +Language features can be roughly put into two categories: + +## Declarative language features + +Declarative language features are defined in configuration files. Examples include [html](https://github.com/Microsoft/vscode/tree/master/extensions/html), [css](https://github.com/Microsoft/vscode/tree/master/extensions/css) and [typescript-basic](https://github.com/Microsoft/vscode/tree/master/extensions/typescript-basics) extensions bundled with VS Code, which offer a subset of the following Declarative Language Features: + +- Syntax highlighting +- Snippet completion +- Bracket matching +- Bracket autoclosing +- Bracket autosurrounding +- Comment toggling +- Auto indentation +- Folding (by markers) + +We have three guides for writing Language Extensions that provide Declarative Language Features. + +- [Syntax Highlight Guide](/api/language-extensions/syntax-highlight-guide): VS Code uses TextMate grammar for syntax highlighting. This guide will walk you through writing a simple TextMate grammar and converting it into a VS Code extension. +- [Snippet Completion Guide](/api/language-extensions/snippet-guide): This guide explains how to bundle a set of snippets into an extension. +- [Language Configuration Guide](/api/language-extensions/language-configuration-guide): VS Code allows extensions to define a **language configuration** for any programming language. This file controls basic editing features such as comment toggling, bracket matching/surrounding and region folding (legacy). + +## Programmatic language features + +Programmatic Language Features include auto completion, error checking, and jump to definition. These features are often powered by a Language Server, a program that analyzes your project to provide the dynamic features. +One example is the [`typescript-language-features`](https://github.com/Microsoft/vscode/tree/master/extensions/typescript-language-features) extension bundled in VS Code. It utilizes the [TypeScript Language Service](https://github.com/Microsoft/TypeScript/wiki/Using-the-Language-Service-API) to offer Programmatic Language Features such as: + +- Hover information ([`vscode.languages.registerHoverProvider`](/api/references/vscode-api#languages.registerHoverProvider)) +- Auto completion ([`vscode.languages.registerCompletionItemProvider`](/api/references/vscode-api#languages.registerCompletionItemProvider)) +- Jump to definition ([`vscode.languages.registerDefinitionProvider`](/api/references/vscode-api#languages.registerDefinitionProvider)) +- Error checking +- Formatting +- Refactoring +- Folding + +Here is a complete list of [Programmatic Language Features](/api/language-extensions/programmatic-language-features). + +![multi-ls](images/overview/multi-ls.png) + +## Language Server Protocol + +By standardizing the communication between a Language Server (a static code analysis tool) and a Language Client (usually a source code editor), the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) allows extension authors to write one code analysis program and reuse it in multiple editors. + +In the [Programmatic Language Features](/api/language-extensions/programmatic-language-features) listing, you can find a listing of all VS Code language features and how they map to the [Language Server Protocol Specification](https://microsoft.github.io/language-server-protocol/specification). + +We offer an in-depth guide that explains how to implement a Language Server extension in VS Code: + +- [Language Server Extension Guide](/api/language-extensions/language-server-extension-guide) + +![multi-editor](images/overview/multi-editor.png) + +## Special cases + +### Multi-root workspace support + +When the user opens a [multi-root workspace](/docs/editor/multi-root-workspaces), you might need to adapt your Language Server extensions accordingly. This topic discusses multiple approaches to supporting multi-root workspaces. + +### Embedded languages + +Embedded languages are common in web development. For example, CSS/JS inside HTML, and GraphQL inside JavaScript/TypeScript. This topic discusses how you can make language features available to embedded languages. diff --git a/api/language-extensions/programmatic-language-features.md b/api/language-extensions/programmatic-language-features.md new file mode 100644 index 0000000000000000000000000000000000000000..006ce8412aa2044c529fef04f19be303803f4826 --- /dev/null +++ b/api/language-extensions/programmatic-language-features.md @@ -0,0 +1,899 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: A9D40038-7837-4320-8C2D-E0CA5769AA69 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Visual Studio Code language extensions contribute programming language features. These guidelines present the language features available in Visual Studio Code and explain the API. +--- + +# Programmatic Language Features + +Programmatic Language Features is a set of smart-editing features powered by the [`vscode.languages.*`](/api/references/vscode-api#languages) API. There are two common ways to provide a dynamic language feature in Visual Studio Code. Let's take [Hover](#hover) as an example: + +```ts +vscode.languages.registerHoverProvider('javascript', { + provideHover(document, position, token) { + return { + contents: ['Hover Content'] + }; + } +}); +``` + +As you see above, the [`vscode.languages.registerHoverProvider`](/api/references/vscode-api#languages.registerHoverProvider) API provides an easy way to provide hover contents to JavaScript files. After this extension gets activated, whenever you hover over some JavaScript code, VS Code queries all [`HoverProvider`](/api/references/vscode-api#HoverProvider) for JavaScript and shows the result in a Hover widget. The [Language Feature Listing](#language-features-listing) and illustrated gif below provides an easy way for you to locate which VS Code API / LSP Method your extension needs. + +An alternative approach is to implement a Language Server that speaks [Language Server Protocol](https://microsoft.github.io/language-server-protocol/). The way it works is: + +- An extension provides a Language Client and a Language Server for JavaScript. +- The Language Client is like any other VS Code extension, running in the Node.js Extension Host context. When it gets activated, it spawns the Language Server in another process and communicates with it through [Language Server Protocol](https://microsoft.github.io/language-server-protocol/). +- You hover over JavaScript code in VS Code +- VS Code informs the Language Client of the hover +- The Language Client queries the Language Server for a hover result and sends it back to VS Code +- VS Code displays the hover result in a Hover widget + +The process seems more complicated, but it provides two major benefits: + +- The Language Server can be written in any language +- The Language Server can be reused to provide smart editing features for multiple editors + +For a more in-depth guide, head over to the [Language Server Extension Guide](/api/language-extensions/language-server-extension-guide). + +--- + +## Language Features Listing + +This listing includes the following items for each language feature: + +- An illustration of the language feature in VS Code +- Related VS Code API +- Related LSP methods + +| VS Code API | LSP method | +| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`createDiagnosticCollection`](/api/references/vscode-api#languages.createDiagnosticCollection) | [PublishDiagnostics](https://microsoft.github.io/language-server-protocol/specification#textDocument_publishDiagnostics) | +| [`registerCompletionItemProvider`](/api/references/vscode-api#languages.registerCompletionItemProvider) | [Completion](https://microsoft.github.io/language-server-protocol/specification#textDocument_completion) & [Completion Resolve](https://microsoft.github.io/language-server-protocol/specification#completionItem_resolve) | +| [`registerHoverProvider`](/api/references/vscode-api#languages.registerHoverProvider) | [Hover](https://microsoft.github.io/language-server-protocol/specification#textDocument_hover) | +| [`registerSignatureHelpProvider`](/api/references/vscode-api#languages.registerSignatureHelpProvider) | [SignatureHelp](https://microsoft.github.io/language-server-protocol/specification#textDocument_signatureHelp) | +| [`registerDefinitionProvider`](/api/references/vscode-api#languages.registerDefinitionProvider) | [Definition](https://microsoft.github.io/language-server-protocol/specification#textDocument_definition) | +| [`registerTypeDefinitionProvider`](/api/references/vscode-api#languages.registerTypeDefinitionProvider) | [TypeDefinition](https://microsoft.github.io/language-server-protocol/specification#textDocument_typeDefinition) | +| [`registerImplementationProvider`](/api/references/vscode-api#languages.registerImplementationProvider) | [Implementation](https://microsoft.github.io/language-server-protocol/specification#textDocument_implementation) | +| [`registerReferenceProvider`](/api/references/vscode-api#languages.registerReferenceProvider) | [References](https://microsoft.github.io/language-server-protocol/specification#textDocument_references) | +| [`registerDocumentHighlightProvider`](/api/references/vscode-api#languages.registerDocumentHighlightProvider) | [DocumentHighlight](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight) | +| [`registerDocumentSymbolProvider`](/api/references/vscode-api#languages.registerDocumentSymbolProvider) | [DocumentSymbol](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentSymbol) | +| [`registerCodeActionsProvider`](/api/references/vscode-api#languages.registerCodeActionsProvider) | [CodeAction](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeAction) | +| [`registerCodeLensProvider`](/api/references/vscode-api#languages.registerCodeLensProvider) | [CodeLens](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeLens) & [CodeLens Resolve](https://microsoft.github.io/language-server-protocol/specification#codeLens_resolve) | +| [`registerDocumentLinkProvider`](/api/references/vscode-api#languages.registerDocumentLinkProvider) | [DocumentLink](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentLink) & [DocumentLink](https://microsoft.github.io/language-server-protocol/specification#documentLink_resolve) | +| [`registerColorProvider`](/api/references/vscode-api#languages.registerDocumentColorProvider) | [DocumentColor](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentColor) & [Color Presentation](https://microsoft.github.io/language-server-protocol/specification#textDocument_colorPresentation) | +| [`registerDocumentFormattingEditProvider`](/api/references/vscode-api#languages.registerDocumentFormattingEditProvider) | [Formatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting) | +| [`registerDocumentRangeFormattingEditProvider`](/api/references/vscode-api#languages.registerDocumentRangeFormattingEditProvider) | [RangeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_rangeFormatting) | +| [`registerOnTypeFormattingEditProvider`](/api/references/vscode-api#languages.registerOnTypeFormattingEditProvider) | [OnTypeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_onTypeFormatting) | +| [`registerRenameProvider`](/api/references/vscode-api#languages.registerRenameProvider) | [Rename](https://microsoft.github.io/language-server-protocol/specification#textDocument_rename) & [Prepare Rename](https://microsoft.github.io/language-server-protocol/specification#textDocument_prepareRename) | +| [`registerFoldingRangeProvider`](/api/references/vscode-api#languages.registerFoldingRangeProvider) | [FoldingRange](https://microsoft.github.io/language-server-protocol/specification#textDocument_foldingRange) | + +## Provide Diagnostics + +Diagnostics are a way to indicate issues with the code. + +![Diagnostics at Work](images/language-support/diagnostics.gif) + +#### Language Server Protocol + +Your language server sends the `textDocument/publishDiagnostics` message to the language client. The message carries an array of diagnostic items for a resource URI. + +**Note**: The client does not ask the server for diagnostics. The server pushes the diagnostic information to the client. + +#### Direct Implementation + +```typescript +let diagnosticCollection: vscode.DiagnosticCollection; + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push(getDisposable()); + diagnosticCollection = vscode.languages.createDiagnosticCollection('go'); + ctx.subscriptions.push(diagnosticCollection); + ... +} + +function onChange() { + let uri = document.uri; + check(uri.fsPath, goConfig).then(errors => { + diagnosticCollection.clear(); + let diagnosticMap: Map = new Map(); + errors.forEach(error => { + let canonicalFile = vscode.Uri.file(error.file).toString(); + let range = new vscode.Range(error.line-1, error.startColumn, error.line-1, error.endColumn); + let diagnostics = diagnosticMap.get(canonicalFile); + if (!diagnostics) { diagnostics = []; } + diagnostics.push(new vscode.Diagnostic(range, error.msg, error.severity)); + diagnosticMap.set(canonicalFile, diagnostics); + }); + diagnosticMap.forEach((diags, file) => { + diagnosticCollection.set(vscode.Uri.parse(file), diags); + }); + }) +} +``` + +> **Basic** +> +> Report diagnostics for open editors. Minimally, this needs to happen on every save. Better, diagnostics should be computed based on the un-saved contents of the editor. + +> **Advanced** +> +> Report diagnostics not only for the open editors but for all resources in the open folder, no matter whether they have ever been opened in an editor or not. + +## Show Code Completion Proposals + +Code completions provide context sensitive suggestions to the user. + +![Code Completion at Work](images/language-support/code-completion.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides completions and whether or not it supports the `completionItem\resolve` method to provide additional information for the computed completion items. + +```json +{ + ... + "capabilities" : { + "completionProvider" : { + "resolveProvider": "true", + "triggerCharacters": [ '.' ] + } + ... + } +} +``` + +#### Direct Implementation + +```typescript +class GoCompletionItemProvider implements vscode.CompletionItemProvider { + public provideCompletionItems( + document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken): + Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push(getDisposable()); + ctx.subscriptions.push( + vscode.languages.registerCompletionItemProvider( + GO_MODE, new GoCompletionItemProvider(), '.', '\"')); + ... +} +``` + +> **Basic** +> +> You don't support resolve providers. + +> **Advanced** +> +> You support resolve providers that compute additional information for completion proposal the user selects. This information is displayed along-side the selected item. + +## Show Hovers + +Hovers show information about the symbol/object that's below the mouse cursor. This is usually the type of the symbol and a description. + +![Hovers at Work](images/language-support/hovers.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides hovers. + +```json +{ + ... + "capabilities" : { + "hoverProvider" : "true", + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/hover` request. + +#### Direct Implementation + +```typescript +class GoHoverProvider implements HoverProvider { + public provideHover( + document: TextDocument, position: Position, token: CancellationToken): + Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerHoverProvider( + GO_MODE, new GoHoverProvider())); + ... +} +``` + +> **Basic** +> +> Show type information and include documentation if available. + +> **Advanced** +> +> Colorize method signatures in the same style you colorize the code. + +## Help With Function and Method Signatures + +When the user enters a function or method, display information about the function/method that is being called. + +![Type Hover](images/language-support/signature-help.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides signature help. + +```json +{ + ... + "capabilities" : { + "signatureHelpProvider" : { + "triggerCharacters": [ '(' ] + } + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/signatureHelp` request. + +#### Direct Implementation + +```typescript +class GoSignatureHelpProvider implements SignatureHelpProvider { + public provideSignatureHelp( + document: TextDocument, position: Position, token: CancellationToken): + Promise { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerSignatureHelpProvider( + GO_MODE, new GoSignatureHelpProvider(), '(', ',')); + ... +} +``` + +> **Basic** +> +> Ensure that the signature help contains the documentation of the parameters of the function or method. + +> **Advanced** +> +> Nothing additional. + +## Show Definitions of a Symbol + +Allow the user to see the definition of variables/functions/methods right where the variables/functions/methods are being used. + +![Type Hover](images/language-support/goto-definition.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides goto-definition locations. + +```json +{ + ... + "capabilities" : { + "definitionProvider" : "true" + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/definition` request. + +#### Direct Implementation + +```typescript +class GoDefinitionProvider implements vscode.DefinitionProvider { + public provideDefinition( + document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken): + Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerDefinitionProvider( + GO_MODE, new GoDefinitionProvider())); + ... +} +``` + +> **Basic** +> +> If a symbol is ambivalent, you can show multiple definitions. + +> **Advanced** +> +> Nothing additional. + +## Find All References to a Symbol + +Allow the user to see all the source code locations where a certain variable/function/method/symbol is being used. + +![Type Hover](images/language-support/find-references.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides symbol reference locations. + +```json +{ + ... + "capabilities" : { + "referencesProvider" : "true" + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/references` request. + +#### Direct Implementation + +```typescript +class GoReferenceProvider implements vscode.ReferenceProvider { + public provideReferences( + document: vscode.TextDocument, position: vscode.Position, + options: { includeDeclaration: boolean }, token: vscode.CancellationToken): + Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerReferenceProvider( + GO_MODE, new GoReferenceProvider())); + ... +} +``` + +> **Basic** +> +> Return the location (resource URI and range) for all references. + +> **Advanced** +> +> Nothing additional. + +## Highlight All Occurrences of a Symbol in a Document + +Allow the user to see all occurrences of a symbol in the open editor. + +![Type Hover](images/language-support/document-highlights.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides symbol document locations. + +```json +{ + ... + "capabilities" : { + "documentHighlightProvider" : "true" + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/documentHighlight` request. + +#### Direct Implementation + +```typescript +class GoDocumentHighlightProvider implements vscode.DocumentHighlightProvider { + public provideDocumentHighlights( + document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken): + vscode.DocumentHighlight[] | Thenable; + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerDocumentHighlightProvider( + GO_MODE, new GoDocumentHighlightProvider())); + ... +} +``` + +> **Basic** +> +> You return the ranges in the editor's document where the references are being found. + +> **Advanced** +> +> Nothing additional. + +## Show all Symbol Definitions Within a Document + +Allow the user to quickly navigate to any symbol definition in the open editor. + +![Type Hover](images/language-support/document-symbols.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides symbol document locations. + +```json +{ + ... + "capabilities" : { + "documentSymbolProvider" : "true" + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/documentSymbol` request. + +#### Direct Implementation + +```typescript +class GoDocumentSymbolProvider implements vscode.DocumentSymbolProvider { + public provideDocumentSymbols( + document: vscode.TextDocument, token: vscode.CancellationToken): + Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerDocumentSymbolProvider( + GO_MODE, new GoDocumentSymbolProvider())); + ... +} +``` + +> **Basic** +> +> Return all symbols in the document. Define the kinds of symbols such as variables, functions, classes, methods, etc. + +> **Advanced** +> +> Nothing additional. + +## Show all Symbol Definitions in Folder + +Allow the user to quickly navigate to symbol definitions anywhere in the folder (workspace) opened in VS Code. + +![Type Hover](images/language-support/workspace-symbols.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides global symbol locations. + +```json +{ + ... + "capabilities" : { + "workspaceSymbolProvider" : "true" + ... + } +} +``` + +In addition, your language server needs to respond to the `workspace/symbol` request. + +#### Direct Implementation + +```typescript +class GoWorkspaceSymbolProvider implements vscode.WorkspaceSymbolProvider { + public provideWorkspaceSymbols( + query: string, token: vscode.CancellationToken): + Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerWorkspaceSymbolProvider( + new GoWorkspaceSymbolProvider())); + ... +} +``` + +> **Basic** +> +> Return all symbols define by the source code within the open folder. Define the kinds of symbols such as variables, functions, classes, methods, etc. + +> **Advanced** +> +> Nothing additional. + +## Possible Actions on Errors or Warnings + +Provide the user with possible corrective actions right next to an error or warning. If actions are available, a light bulb appears next to the error or warning. When the user clicks the light bulb, a list of available Code Actions is presented. + +![Type Hover](images/language-support/quick-fixes.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides Code Actions. + +```json +{ + ... + "capabilities" : { + "codeActionProvider" : "true" + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/codeAction` request. + +#### Direct Implementation + +```typescript +class GoCodeActionProvider implements vscode.CodeActionProvider { + public provideCodeActions( + document: vscode.TextDocument, range: vscode.Range, + context: vscode.CodeActionContext, token: vscode.CancellationToken): + Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerCodeActionsProvider( + GO_MODE, new GoCodeActionProvider())); + ... +} +``` + +> **Basic** +> +> Provide Code Actions for error/warning correcting actions. + +> **Advanced** +> +> In addition, provide source code manipulation actions such as refactoring. For example, **Extract Method**. + +## CodeLens - Show Actionable Context Information Within Source Code + +Provide the user with actionable, contextual information that is displayed interspersed with the source code. + +![Type Hover](images/language-support/code-lens.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides CodeLens results and whether it supports the `codeLens\resolve` method to bind the CodeLens to its command. + +```json +{ + ... + "capabilities" : { + "codeLensProvider" : { + "resolveProvider": "true" + } + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/codeLens` request. + +#### Direct Implementation + +```typescript +class GoCodeLensProvider implements vscode.CodeLensProvider { + public provideCodeLenses(document: TextDocument, token: CancellationToken): + CodeLens[] | Thenable { + ... + } + + public resolveCodeLens?(codeLens: CodeLens, token: CancellationToken): + CodeLens | Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerCodeLensProvider( + GO_MODE, new GoCodeLensProvider())); + ... +} +``` + +> **Basic** +> +> Define the CodeLens results that are available for a document. + +> **Advanced** +> +> Bind the CodeLens results to a command by responding to `codeLens/resolve`. + +## Show Color Decorators + +Allow the user to preview and modify colors in the document. + +![Type Hover](images/language-support/color-decorators.png) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides color information. + +```json +{ + ... + "capabilities" : { + "colorProvider" : "true" + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/documentColor` and `textDocument/colorPresentation` requests. + +#### Direct Implementation + +```typescript +class GoColorProvider implements vscode.DocumentColorProvider { + public provideDocumentColors( + document: vscode.TextDocument, token: vscode.CancellationToken): + Thenable { + ... + } + public provideColorPresentations( + color: Color, context: { document: TextDocument, range: Range }, token: vscode.CancellationToken): + Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerColorProvider( + GO_MODE, new GoColorProvider())); + ... +} +``` + +> **Basic** +> +> Return all color references in the document. Provide color presentations for the color formats supported (for example rgb(...), hsl(...)). + +> **Advanced** +> +> Nothing additional. + +## Format Source Code in an Editor + +Provide the user with support for formatting whole documents. + +![Document Formatting at Work](images/language-support/format-document.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides document formatting. + +```json +{ + ... + "capabilities" : { + "documentFormattingProvider" : "true" + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/formatting` request. + +#### Direct Implementation + +```typescript +class GoDocumentFormatter implements vscode.DocumentFormattingEditProvider { + public formatDocument(document: vscode.TextDocument): + Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerDocumentFormattingEditProvider( + GO_MODE, new GoDocumentFormatter())); + ... +} +``` + +> **Basic** +> +> Don't provide formatting support. + +> **Advanced** +> +> You should always return the smallest possible text edits that result in the source code being formatted. This is crucial to ensure that markers such as diagnostic results are adjusted correctly and are not lost. + +## Format the Selected Lines in an Editor + +Provide the user with support for formatting a selected range of lines in a document. + +![Document Formatting at Work](images/language-support/format-document-range.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides formatting support for ranges of lines. + +```json +{ + ... + "capabilities" : { + "documentRangeFormattingProvider" : "true" + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/rangeFormatting` request. + +#### Direct Implementation + +```typescript +class GoDocumentRangeFormatter implements vscode.DocumentRangeFormattingEditProvider{ + public provideDocumentRangeFormattingEdits( + document: vscode.TextDocument, range: vscode.Range, + options: vscode.FormattingOptions, token: vscode.CancellationToken): + Thenable; + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerDocumentRangeFormattingEditProvider( + GO_MODE, new GoDocumentRangeFormatter())); + ... +} +``` + +> **Basic** +> +> Don't provide formatting support. + +> **Advanced** +> +> You should always return the smallest possible text edits that result in the source code being formatted. This is crucial to ensure that markers such as diagnostic results are adjusted corrected and are not lost. + +## Incrementally Format Code as the User Types + +Provide the user with support for formatting text as they type. + +**Note**: The user [setting](/docs/getstarted/settings) `editor.formatOnType` controls whether source code gets formatted or not as the user types. + +![Document Formatting at Work](images/language-support/format-on-type.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides formatting as the user types. It also needs to tell the client on which characters formatting should be triggered. `moreTriggerCharacters` is optional. + +```json +{ + ... + "capabilities" : { + "documentOnTypeFormattingProvider" : { + "firstTriggerCharacter": "}", + "moreTriggerCharacter": [";", ","] + } + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/onTypeFormatting` request. + +#### Direct Implementation + +```typescript +class GoOnTypingFormatter implements vscode.OnTypeFormattingEditProvider{ + public provideOnTypeFormattingEdits( + document: vscode.TextDocument, position: vscode.Position, + ch: string, options: vscode.FormattingOptions, token: vscode.CancellationToken): + Thenable; + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerOnTypeFormattingEditProvider( + GO_MODE, new GoOnTypingFormatter())); + ... +} +``` + +> **Basic** +> +> Don't provide formatting support. + +> **Advanced** +> +> You should always return the smallest possible text edits that result in the source code being formatted. This is crucial to ensure that markers such as diagnostic results are adjusted corrected and are not lost. + +## Rename Symbols + +Allow the user to rename a symbol and update all references to the symbol. + +![Type Hover](images/language-support/rename.gif) + +#### Language Server Protocol + +In the response to the `initialize` method, your language server needs to announce that it provides for renaming. + +```json +{ + ... + "capabilities" : { + "renameProvider" : "true" + ... + } +} +``` + +In addition, your language server needs to respond to the `textDocument/rename` request. + +#### Direct Implementation + +```typescript +class GoRenameProvider implements vscode.RenameProvider { + public provideRenameEdits( + document: vscode.TextDocument, position: vscode.Position, + newName: string, token: vscode.CancellationToken): + Thenable { + ... + } +} + +export function activate(ctx: vscode.ExtensionContext): void { + ... + ctx.subscriptions.push( + vscode.languages.registerRenameProvider( + GO_MODE, new GoRenameProvider())); + ... +} +``` + +> **Basic** +> +> Don't provide rename support. + +> **Advanced** +> +> Return the list of all workspace edits that need to be performed, for example all edits across all files that contain references to the symbol. diff --git a/api/language-extensions/smart-editing-guide.md b/api/language-extensions/smart-editing-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..4b1813ca3be6709d2d7927888705976ac9da9674 --- /dev/null +++ b/api/language-extensions/smart-editing-guide.md @@ -0,0 +1,11 @@ +--- +DateApproved: +MetaDescription: +--- + +# Smart Editing Guide + +This page should: + +- Point to a reference topic that lists every language feature that's available. +- Illustrate a sample that uses `vscode.langauges.registerCompletionProvider` API and `vscode.languages.createDiagnosticCollection` API for completion and diagnostics diff --git a/api/language-extensions/snippet-guide.md b/api/language-extensions/snippet-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..3778486213edc1f150be47ace104f1e4573b3427 --- /dev/null +++ b/api/language-extensions/snippet-guide.md @@ -0,0 +1,56 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 4b24790b-781a-43cc-afe6-58b1d57d6163 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Learn how to bundle snippets into an extension (plug-in) for Visual Studio Code +--- + +# Snippet Guide + +The [`contributes.snippets`](/api/references/contribution-points#contributes.snippets) Contribution Point allows you to bundle snippets into a Visual Studio Code extension for sharing. + +The [Creating snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_creating-your-own-snippets) topic contains all information for creating snippets. This guide / sample just shows how you can turn your own snippets into an extension for sharing. The suggested workflow is: + +- Create and test your snippets using `Preferences: Configure User Snippets` command +- Once you are happy with the snippets, copy the whole JSON file into an extension folder, such as `snippets.json` +- Add the following snippet contribution to your `package.json` + +```json +{ + "contributes": { + "snippets": [ + { + "language": "javascript", + "path": "./snippets.json" + } + ] + } +} +``` + +You can find the complete source code at: https://github.com/Microsoft/vscode-extension-samples/tree/master/snippet-sample + +**Tip**: Tag your extension as a snippet extension with the following config in your `package.json`: + +```json +{ + "categories": ["Snippets"] +} +``` + +## Using TextMate snippets + +You can also add TextMate snippets (.tmSnippets) to your VS Code installation using the [yo code](/api/get-started/your-first-extension) extension generator. The generator has an option `New Code Snippets` which lets you point to a folder containing multiple .tmSnippets files and they will be packaged into a VS Code snippet extension. The generator also supports Sublime snippets (.sublime-snippets). + +The final generator output has two files: an extension manifest `package.json` which has metadata to integrate the snippets into VS Code and a `snippets.json` file which includes the snippets converted to the VS Code snippet format. + +```bash +. +├── snippets // VS Code integration +│   └── snippets.json // The JSON file w/ the snippets +└── package.json // extension's manifest +``` + +Copy the generated snippets folder to a new folder under your `.vscode/extensions` folder and restart VS Code. diff --git a/api/language-extensions/syntax-highlight-guide.md b/api/language-extensions/syntax-highlight-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..1cc6d41a1bc657b828f931c5b583ff94b841adbe --- /dev/null +++ b/api/language-extensions/syntax-highlight-guide.md @@ -0,0 +1,328 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 2bb06188-d394-4b98-872c-0bf26c8a674d +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: A guide to +--- + +# Syntax Highlight Guide + +Syntax highlighting determines the color and style of source code displayed in the Visual Studio Code editor. It is responsible for colorizing keywords like `if` or `for` in JavaScript differently than strings and comments and variable names. + +There are two components to syntax highlighting: + +- Breaking text into a list of tokens and scopes using a grammar +- Then using a theme to map these scopes to specific colors and styles + +This document only discusses the first part: breaking text into tokens and scopes that existing color themes can colorize. For more information about customizing the styling of different scopes in the editor, see the [Color Theme Guide](/api/extension-guides/color-theme#syntax-colors) + +## TextMate grammars + +VS Code uses [TextMate grammars][tm-grammars] to break text into a list of tokens. TextMate grammars are a structured collection of [Oniguruma regular expressions](https://macromates.com/manual/en/regular_expressions) and are typically written as a plist or JSON. You can find a good introduction to TextMate grammars [here](https://www.apeth.com/nonblog/stories/textmatebundle.html), and you can take a look at existing TextMate grammars to learn more about how they work. + +### Tokens and scopes + +Tokens are one or more characters that are part of the same program element. Example tokens include operators such as `+` and `*`, variable names such as `myVar`, or strings such as `"my string"`. + +Each token is associated with a scope that defines the context of the token. A scope is a dot separated list of identifiers that specify the context of the current token. The `+` operation in JavaScript for example has the scope `keyword.operator.arithmetic.js`. + +Themes map scopes to colors and styles to provide syntax highlighting. TextMate provides [list of common scopes][tm-grammars] that many themes target. In order to have your grammar as broadly supported as possible, try to build on existing scopes rather than defining new ones. + +Scopes nest so that each token is also associated with a list of parent scopes. The example below uses the [scope inspector](#scope-inspector) to show the scope hierarchy for the `+` operator in a simple JavaScript function. The most specific scope is listed at the top, with more general parent scopes listed below: + +![syntax highlighting scopes](images/syntax-highlighting/scopes.png) + +Parent scope information is also used for theming. When a theme targets a scope, all tokens with that parent scope will be colorized unless the theme also provides a more specific colorization for their individual scopes. + +### Contributing a basic grammar + +VS Code supports json TextMate grammars. These are contributed through the `grammars` [contribution point](/api/references/contribution-points). + +Each grammar contribution specifies: the identifier of the language the grammar applies to, the top level scope name for the tokens of the grammar, and the relative path to a grammar file. The example below shows a grammar contribution for a fictional `abc` language: + +```json +{ + "contributes": { + "languages": [ + { + "id": "abc", + "extensions": [".abc"] + } + ], + "grammars": [ + { + "language": "abc", + "scopeName": "source.abc", + "path": "./syntaxes/abc.tmGrammar.json" + } + ] + } +} +``` + +The grammar file itself consists of a top level rule. This is typically split into a `patterns` section that lists the top level elements of the program and a `repository` that defines each of the elements. Other rules in the grammar can reference elements from the `repository` using `{ "include": "#id" }`. + +The example `abc` grammar marks the letters `a`, `b`, and `c` as keywords, and nestings of parens as expressions. + +```json +{ + "scopeName": "source.abc", + "patterns": [{ "include": "#expression" }], + "repository": { + "expression": { + "patterns": [{ "include": "#letter" }, { "include": "#paren-expression" }] + }, + "letter": { + "match": "a|b|c", + "name": "keyword.letter" + }, + "paren-expression": { + "begin": "\\(", + "end": "\\)", + "beginCaptures": { + "0": { "name": "punctuation.paren.open" } + }, + "endCaptures": { + "0": { "name": "punctuation.paren.close" } + }, + "name": "expression.group", + "patterns": [{ "include": "#expression" }] + } + } +} +``` + +The grammar engine will try to successively apply the `expression` rule to all text in the document. For a simple program such as: + +``` +a +( + b +) +x +( + ( + c + xyz + ) +) +( +a +``` + +The example grammar produces the following scopes (listed left-to-right from most specific to least specific scope): + +``` +a keyword.letter, source.abc +( punctuation.paren.open, expression.group, source.abc + b expression.group, source.abc +) punctuation.paren.close, expression.group, source.abc +x source.abc +( punctuation.paren.open, expression.group, source.abc + ( punctuation.paren.open, expression.group, expression.group, source.abc + c keyword.letter, expression.group, expression.group, source.abc + xyz expression.group, expression.group, source.abc + ) punctuation.paren.close, expression.group, expression.group, source.abc +) punctuation.paren.close, expression.group, source.abc +( source.abc +a keyword.letter, source.abc +``` + +Note that text that is not matched by one of the rules, such as the string `xyz`, is included in the current scope. The last paren at the end of the file is not part of the an `expression.group` since the `end` rule is not matched. + +### Embedded languages + +If your grammar include embedded languages within the parent language, such as CSS style blocks in HTML, you can use the `embeddedLanguages` contribution point to tell VS Code to treat the embedded language as distinct from the parent language. This ensures that bracket matching, commenting, and other basic language features work as expected in the embedded language. + +The `embeddedLanguages` contribution point maps a scope in the embedded language to a top level language scope. In the example below, any tokens in the `meta.embedded.block.javascript` scope will be treated as javascript content: + +```json +{ + "contributes": { + "grammars": [ + { + "path": "./syntaxes/abc.tmLanguage.json", + "scopeName": "source.abc", + "embeddedLanguages": { + "meta.embedded.block.javascript": "source.js" + } + } + ] + } +} +``` + +Now if you try to comment code or trigger snippets inside an set of tokens marked `meta.embedded.block.javascript`, they will get the correct `//` JavaScript style comment and the correct JavaScript snippets. + +## Developing a new grammar extension + +To quickly create a new grammar extension, use [VS Code's Yeoman templates](/api/get-started/your-first-extension) to run `yo code` and select the `New Language` option: + +![Selecting the 'new language' template in 'yo code'](images/syntax-highlighting/yo-new-language.png) + +Yeoman will walk you through some basic questions to scaffold the new extension. The important questions for creating a new grammar are: + +- `Language Id` - A unique identifier for your language. +- `Language Name` - A human readable name for your language. +- `Scope names` - Root TextMate scope name for your grammar + +![Filling in the 'new language' questions](images/syntax-highlighting/yo-new-language-questions.png) + +The generator assumes that you want to define both a new language and a new grammar for that language. If you are creating a grammar for an existing language, just fill these in with your target language's information and be sure to delete the `languages` contribution point in the generated `package.json`. + +After answering all the questions, Yeoman will create a new extension with the structure: + +![A new language extension](images/syntax-highlighting/generated-new-language-extension.png) + +Remember, if you are contributing a grammar to a language that VS Code already knows about, be sure to delete the `languages` contribution point in the generated `package.json`. + +### Converting an existing TextMate grammar + +`yo code` can also help convert an existing TextMate grammar to a VS Code extension. Again, start by running `yo code` and selecting `Language extension`. When asked for an existing grammar file, give it the full path to either a `.tmLanguage` or `.json` TextMate grammar file: + +![Converting an existing TextMate grammar](images/syntax-highlighting/yo-convert.png) + +### Using YAML to write a grammar + +As a grammar grows more complex, it can become difficult to understand and maintain it as json. If you find yourself writing complex regular expressions or needing to add comments to explain aspects of the grammar, consider using yaml to define your grammar instead. + +Yaml grammars have the exact same structure as a json based grammar but allow you to use yaml's more concise syntax, along with features such as multi-line strings and comments. + +![A yaml grammar using multiline strings and comments](images/syntax-highlighting/yaml-grammar.png) + +VS Code can only load json grammars, so yaml based grammars must be converted to json. The [`js-yaml` package](https://www.npmjs.com/package/js-yaml) and command line tool makes this easy. + +```bash +# Install js-yaml as a development only dependency in your extension +$ npm install js-yaml --save-dev + +# Use the command line tool to convert the yaml grammar to json +$ npx js-yaml syntaxes/abc.tmLanguage.yaml > syntaxes/abc.tmLanguage.json +``` + +### Scope inspector + +VS Code's built-in scope inspector tool helps debug grammars. It displays the scopes for the token at the current position in a file, along with metadata about which theme rules apply to that token. + +Trigger the scope inspector from the command palette with the `Developer: Inspect TM Scopes` command or [create a keybinding](/docs/getstarted/keybindings) for it: + +```json +{ + "key": "cmd+alt+shift+i", + "command": "editor.action.inspectTMScopes" +} +``` + +![scope inspector](images/syntax-highlighting/scope-inspector.png) + +The scope inspector displays the following information: + +1. The current token. +1. Metadata about the token and information about its computed appearance. If you are working with embedded languages, the important entries here `language` and `token type`. +1. Theme rules that apply to the token. This only shows the theme rules that are responsible for the token's current style, it does not show overridden rules. +1. Complete scope list, with the most specific scope at the top. + +## Injection grammars + +Injection grammars let you extend an existing grammar. An injection grammar is a regular TextMate grammar that is injected into a specific scope within an existing grammar. Example applications of injection grammars: + +- Highlighting keywords such as `TODO` in comments. +- Add more specific scope information to an existing grammar. +- Adding highlighting for a new language to Markdown fenced code blocks. + +### Creating a basic injection grammar + +Injection grammars are contributed though the `package.json` just like regular grammars. However, instead of specifying a `language`, an injection grammar uses `injectTo` to specify a list of target language scopes to inject the grammar into. + +For this example, we'll create a very simple injection grammar that highlights `TODO` as a keyword in javascript comments. To apply our injection grammar in javascript files, we use the `source.js` target language scope in `injectTo`: + +```json +{ + "contributes": { + "grammars": [ + { + "path": "./syntaxes/injection.json", + "scopeName": "todo-comment.injection", + "injectTo": ["source.js"] + } + ] + } +} +``` + +The grammar itself is a standard TextMate grammar except for the top level `injectionSelector` entry. The `injectionSelector` is a scope selector that specifies which scopes the injected grammar should be applied in. For our example, we want to highlight the word `TODO` in all `//` comments. Using the [scope inspector](#scope-inspector), we find that JavaScript's double slash comments have the scope `comment.line.double-slash`, so our injection selector is `L:comment.line.double-slash`: + +```json +{ + "scopeName": "todo-comment.injection", + "injectionSelector": "L:comment.line.double-slash", + "patterns": [ + { + "include": "#todo-keyword" + } + ], + "repository": { + "todo-keyword": { + "match": "TODO", + "name": "keyword.todo" + } + } +} +``` + +The `L:` in the injection selector means that the injection is added to the left of existing grammar rules. This basically means that our injected grammar's rules will be applied before any existing grammar rules. + +### Embedded languages + +Injection grammars can also contribute embedded languages to their parent grammar. Just like with a normal grammar, an injection grammars can use `embeddedLanguages` to map scopes from the embedded language to a top level language scope. + +An extension that highlights sql queries in javascript strings for example may use `embeddedLanguages` to make sure all token inside the string marked `meta.embedded.inline.sql` are treated as sql for basic language features such as bracket matching and snippet selection. + +```json +{ + "contributes": { + "grammars": [ + { + "path": "./syntaxes/injection.json", + "scopeName": "sql-string.injection", + "injectTo": ["source.js"], + "embeddedLanguages": { + "meta.embedded.inline.sql": "source.sql" + } + } + ] + } +} +``` + +### Token types and embedded languages + +There is one additional complication for injection languages embedded languages: by default, VS Code treats all tokens within a string as string contents and all tokens with a comment as token content. Since features such as bracket matching and auto closing pairs are disabled inside of strings and comments, if the embedded language appears inside a string or comment, these features will also be disabled in the embedded language. + +To override this behavior, you can use a `meta.embedded.*` scope to reset VS Code's marking of tokens as string or comment content. It is a good idea to always wrap embedded language in a `meta.embedded.*` scope to make sure VS Code treats the embedded language properly. + +If you can't add a `meta.embedded.*` scope to your grammar, you can alternatively use `tokenTypes` in the grammar's contribution point to map specific scopes to content mode. The `tokenTypes` section below ensures that any content in the `my.sql.template.string` scope is treated as source code: + +```json +{ + "contributes": { + "grammars": [ + { + "path": "./syntaxes/injection.json", + "scopeName": "sql-string.injection", + "injectTo": ["source.js"], + "embeddedLanguages": { + "my.sql.template.string": "source.sql" + }, + "tokenTypes": { + "my.sql.template.string": "other" + } + } + ] + } +} +``` + +[tm-grammars]: https://macromates.com/manual/en/language_grammars diff --git a/api/references/activation-events.md b/api/references/activation-events.md new file mode 100644 index 0000000000000000000000000000000000000000..ca41282760ed1728863c0c6f336a0aebe57f0d26 --- /dev/null +++ b/api/references/activation-events.md @@ -0,0 +1,171 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: C83BB647-A37E-45CE-BA4C-837B397C2ABE +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: To support lazy activation of Visual Studio Code extensions (plug-ins), your extension controls when it should be loaded through a set of Activation Events. +--- + +# Activation Events + +**Activation Events** is a set of JSON declarations that you make in the `activationEvents` field of `package.json` [Extension Manifest](/api/references/extension-manifest). Your extension becomes activated when the **Activation Event** happens. Here is a list of all available **Activation Events**: + +- [`onLanguage`](/api/references/activation-events#onLanguage) +- [`onCommand`](/api/references/activation-events#onCommand) +- [`onDebug`](/api/references/activation-events#onDebug) + - [`onDebugInitialConfigurations`](/api/references/activation-events#onDebugInitialConfigurations) + - [`onDebugResolve`](/api/references/activation-events#onDebugResolve) +- [`workspaceContains`](/api/references/activation-events#workspaceContains) +- [`onFileSystem`](/api/references/activation-events#onFileSystem) +- [`onView`](/api/references/activation-events#onView) +- [`onUri`](/api/references/activation-events#onUri) +- [`onWebviewPanel`](/api/references/activation-events#onWebviewPanel) +- [`*`](/api/references/activation-events#Start-up) + +We also provide a reference of all fields in the [`package.json` extension manifest](/api/references/extension-manifest). + +## onLanguage + +This activation event is emitted and interested extensions will be activated whenever a file that resolves to a certain language gets opened. + +```json +... +"activationEvents": [ + "onLanguage:python" +] +... +``` + +The `onLanguage` event takes a [language identifier](/docs/languages/identifiers) value. + +Multiple languages can be declared with separate `onLanguage` entries in the `activationEvents` array. + +```json +"activationEvents": [ + "onLanguage:json", + "onLanguage:markdown", + "onLanguage:typescript" +] +... +``` + +## onCommand + +This activation event is emitted and interested extensions will be activated whenever a command is being invoked: + +```json +... +"activationEvents": [ + "onCommand:extension.sayHello" +] +... +``` + +## onDebug + +This activation event is emitted and interested extensions will be activated before a debug session is started: + +```json +... +"activationEvents": [ + "onDebug" +] +... +``` + +### onDebugInitialConfigurations + +### onDebugResolve + +These are two more fine-grained `onDebug` activation events: + +- `onDebugInitialConfigurations` is fired just before the `provideDebugConfigurations` method of the `DebugConfigurationProvider` is called. +- `onDebugResolve:type` is fired just before the `resolveDebugConfiguration` method of the `DebugConfigurationProvider` for the specified type is called. + +**Rule of thumb:** If activation of a debug extension is lightweight, use `onDebug`. If it is heavyweight, use `onDebugInitialConfigurations` and/or `onDebugResolve` depending on whether the `DebugConfigurationProvider` implements the corresponding methods `provideDebugConfigurations` and/or `resolveDebugConfiguration`. See [Using a DebugConfigurationProvider](/api/extension-guides/debugger-extension#using-a-debugconfigurationprovider) for more details on these methods. + +## workspaceContains + +This activation event is emitted and interested extensions will be activated whenever a folder is opened and the folder contains at least one file that matches a glob pattern. + +```json +... +"activationEvents": [ + "workspaceContains:**/.editorconfig" +] +... +``` + +## onFileSystem + +This activation event is emitted and interested extensions will be activated whenever a file or folder from a specific _scheme_ is read. This is usually the `file`-scheme, but with custom file system providers more schemes come into place, e.g `ftp` or `ssh`. + +```json +... +"activationEvents": [ + "onFileSystem:sftp" +] +... +``` + +## onView + +This activation event is emitted and interested extensions will be activated whenever a view of the specified id is expanded: + +```json +... +"activationEvents": [ + "onView:nodeDependencies" +] +... +``` + +## onUri + +This activation event is emitted and interested extensions will be activated whenever a system-wide Uri for that extension is opened. The Uri scheme is fixed to either `vscode` or `vscode-insiders`. The Uri authority must be the extension's identifier. The rest of the Uri is arbitrary. + +```json +... +"activationEvents": [ + "onUri" +] +... +``` + +If the `vscode.git` extension defines `onUri` as an activation event, it will be activated in any of the following Uris are open: + +- `vscode://vscode.git/init` +- `vscode://vscode.git/clone?url=https%3A%2F%2Fgithub.com%2FMicrosoft%2Fvscode-vsce.git` +- `vscode-insiders://vscode.git/init` (for VS Code Insiders) + +## onWebviewPanel + +This activation event is emitted and interested extensions will be activated whenever VS Code needs to restore a webview with the matching `viewType`. + +For example, the declaration of onWebviewPanel below: + +```json +"activationEvents": [ + ..., + "onWebviewPanel:catCoding" +] +``` + +will cause the extension to be activated when VS Code needs to restore a webview with the viewType: `catCoding`. The viewType is set in the call to `window.createWebviewPanel` and you will need to have another activation event (for example, onCommand) to initially activate your extension and create the webview. + +## Start up + +The `*` activation event is emitted and interested extensions will be activated whenever VS Code starts up. To ensure a great end user experience, please use this activation event in your extension only when no other activation events combination works in your use-case. + +```json +... +"activationEvents": [ + "*" +] +... +``` + +> **Note:** An extension can listen to multiple activation events, and that is preferable to listening to `"*"`. + +> **Note:** An extension **must** export an `activate()` function from its main module and it will be invoked **only once** by VS Code when any of the specified activation events is emitted. Also, an extension **should** export a `deactivate()` function from its main module to perform cleanup tasks on VS Code shutdown. Extension **must** return a Promise from `deactivate()` if the cleanup process is asynchronous. An extension may return `undefined` from `deactivate()` if the cleanup runs synchronously. diff --git a/api/references/commands.md b/api/references/commands.md new file mode 100644 index 0000000000000000000000000000000000000000..50bc8a20e821baccca18b1412b876325898e5d59 --- /dev/null +++ b/api/references/commands.md @@ -0,0 +1,282 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: A010AEDF-EF37-406E-96F5-E129408FFDE1 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Visual Studio Code built-in commands reference. +--- + +# Built-in Commands + +This document lists a subset of Visual Studio Code commands that you might use with `vscode.commands.executeCommand` API. + +Read the [Commands Guide](/api/extension-guides/command) for how to use the commands API. + +The following is a sample of how to open a new folder in VS Code: + +```javascript +let uri = Uri.file('/some/path/to/folder'); +let success = await commands.executeCommand('vscode.openFolder', uri); +``` + +## Commands + +`vscode.executeWorkspaceSymbolProvider` - Execute all workspace symbol provider. + +- _query_ - Search string +- _(returns)_ - A promise that resolves to an array of SymbolInformation and DocumentSymbol instances. + +`vscode.executeDefinitionProvider` - Execute all definition provider. + +- _uri_ - Uri of a text document +- _position_ - Position of a symbol +- _(returns)_ - A promise that resolves to an array of Location instances. + +`vscode.executeDeclarationProvider` - Execute all declaration provider. + +- _uri_ - Uri of a text document +- _position_ - Position of a symbol +- _(returns)_ - A promise that resolves to an array of Location-instances. + +`vscode.executeTypeDefinitionProvider` - Execute all type definition providers. + +- _uri_ - Uri of a text document +- _position_ - Position of a symbol +- _(returns)_ - A promise that resolves to an array of Location instances. + +`vscode.executeImplementationProvider` - Execute all implementation providers. + +- _uri_ - Uri of a text document +- _position_ - Position of a symbol +- _(returns)_ - A promise that resolves to an array of Location instances. + +`vscode.executeHoverProvider` - Execute all hover provider. + +- _uri_ - Uri of a text document +- _position_ - Position of a symbol +- _(returns)_ - A promise that resolves to an array of Hover instances. + +`vscode.executeDocumentHighlights` - Execute document highlight provider. + +- _uri_ - Uri of a text document +- _position_ - Position in a text document +- _(returns)_ - A promise that resolves to an array of DocumentHighlight instances. + +`vscode.executeReferenceProvider` - Execute reference provider. + +- _uri_ - Uri of a text document +- _position_ - Position in a text document +- _(returns)_ - A promise that resolves to an array of Location instances. + +`vscode.executeDocumentRenameProvider` - Execute rename provider. + +- _uri_ - Uri of a text document +- _position_ - Position in a text document +- _newName_ - The new symbol name +- _(returns)_ - A promise that resolves to a WorkspaceEdit. + +`vscode.executeSignatureHelpProvider` - Execute signature help provider. + +- _uri_ - Uri of a text document +- _position_ - Position in a text document +- _triggerCharacter_ - (optional) Trigger signature help when the user types the character, like `,` or `(` +- _(returns)_ - A promise that resolves to SignatureHelp. + +`vscode.executeDocumentSymbolProvider` - Execute document symbol provider. + +- _uri_ - Uri of a text document +- _(returns)_ - A promise that resolves to an array of SymbolInformation and DocumentSymbol instances. + +`vscode.executeCompletionItemProvider` - Execute completion item provider. + +- _uri_ - Uri of a text document +- _position_ - Position in a text document +- _triggerCharacter_ - (optional) Trigger completion when the user types the character, like `,` or `(` +- _itemResolveCount_ - (optional) Number of completions to resolve (too large numbers slow down completions) +- _(returns)_ - A promise that resolves to a CompletionList instance. + +`vscode.executeCodeActionProvider` - Execute code action provider. + +- _uri_ - Uri of a text document +- _range_ - Range in a text document +- _(returns)_ - A promise that resolves to an array of Command instances. + +`vscode.executeCodeLensProvider` - Execute CodeLens provider. + +- _uri_ - Uri of a text document +- _itemResolveCount_ - (optional) Number of lenses that should be resolved and returned. Will only return resolved lenses, will impact performance) +- _(returns)_ - A promise that resolves to an array of CodeLens instances. + +`vscode.executeFormatDocumentProvider` - Execute document format provider. + +- _uri_ - Uri of a text document +- _options_ - Formatting options +- _(returns)_ - A promise that resolves to an array of TextEdits. + +`vscode.executeFormatRangeProvider` - Execute range format provider. + +- _uri_ - Uri of a text document +- _range_ - Range in a text document +- _options_ - Formatting options +- _(returns)_ - A promise that resolves to an array of TextEdits. + +`vscode.executeFormatOnTypeProvider` - Execute document format provider. + +- _uri_ - Uri of a text document +- _position_ - Position in a text document +- _ch_ - Character that got typed +- _options_ - Formatting options +- _(returns)_ - A promise that resolves to an array of TextEdits. + +`vscode.executeLinkProvider` - Execute document link provider. + +- _uri_ - Uri of a text document +- _(returns)_ - A promise that resolves to an array of DocumentLink instances. + +`vscode.executeDocumentColorProvider` - Execute document color provider. + +- _uri_ - Uri of a text document +- _(returns)_ - A promise that resolves to an array of ColorInformation objects. + +`vscode.executeColorPresentationProvider` - Execute color presentation provider. + +- _color_ - The color to show and insert +- _context_ - Context object with uri and range +- _(returns)_ - A promise that resolves to an array of ColorPresentation objects. + +`vscode.previewHtml` - Render the HTML of the resource in an editor view. + +**🚨 The previewHtml command is deprecated. Please use the [Webview API](/api/extension-guides/webview) instead** + +- _uri_ - Uri of the resource to preview. +- _column_ - (optional) Column in which to preview. +- _label_ - (optional) An human readable string that is used as title for the preview. +- _options_ - (optional) Options for controlling webview environment. + +`vscode.openFolder` - Open a folder or workspace in the current window or new window depending on the newWindow argument. + +- _uri_ - (optional) Uri of the folder or workspace file to open. If not provided, a native dialog will ask the user for the folder +- _newWindow_ - (optional) Whether to open the folder/workspace in a new window or the same. Defaults to opening in the same window. + +Note that opening in the same window will shutdown the current extension host process and start a new one on the given folder/workspace unless the newWindow parameter is set to true. + +`vscode.diff` - Opens the provided resources in the diff editor to compare their contents. + +- _left_ - Left-hand side resource of the diff editor +- _right_ - Right-hand side resource of the diff editor +- _title_ - (optional) Human readable title for the diff editor +- _options_ - (optional) Editor options, see vscode.TextDocumentShowOptions + +`vscode.open` - Opens the provided resource in the editor. + +- _resource_ - Resource to open +- _columnOrOptions_ - (optional) Either the column in which to open or editor options, see vscode.TextDocumentShowOptions + +Can be a text or binary file, or a http(s) url. If you need more control over the options for opening a text file, use vscode.window.showTextDocument instead. + +`vscode.removeFromRecentlyOpened` - Removes an entry with the given path from the recently opened list. + +- _path_ - Path to remove from recently opened. + +`vscode.setEditorLayout` - Sets the editor layout. + +- _layout_ - The editor layout to set. + +The layout is described as object with an initial (optional) orientation (0 = horizontal, 1 = vertical) and an array of editor groups within. Each editor group can have a size and another array of editor groups that will be laid out orthogonal to the orientation. If editor group sizes are provided, their sum must be 1 to be applied per row or column. Example for a 2x2 grid: `{ orientation: 0, groups: [{ groups: [{}, {}], size: 0.5 }, { groups: [{}, {}], size: 0.5 }] }` + +`cursorMove` - Move cursor to a logical position in the view + +- _Cursor move argument object_ + + Property-value pairs that can be passed through this argument: + + - 'to': A mandatory logical position value providing where to move the cursor. + ``` + 'left', 'right', 'up', 'down' + 'wrappedLineStart', 'wrappedLineEnd', 'wrappedLineColumnCenter' + 'wrappedLineFirstNonWhitespaceCharacter', 'wrappedLineLastNonWhitespaceCharacter' + 'viewPortTop', 'viewPortCenter', 'viewPortBottom', 'viewPortIfOutside' + ``` + - 'by': Unit to move. Default is computed based on 'to' value. + ``` + 'line', 'wrappedLine', 'character', 'halfLine' + ``` + - 'value': Number of units to move. Default is '1'. + - 'select': If 'true' makes the selection. Default is 'false'. + +`editorScroll` - Scroll editor in the given direction + +- _Editor scroll argument object_ + + Property-value pairs that can be passed through this argument: + + - 'to': A mandatory direction value. + ``` + 'up', 'down' + ``` + - 'by': Unit to move. Default is computed based on 'to' value. + ``` + 'line', 'wrappedLine', 'page', 'halfPage' + ``` + - 'value': Number of units to move. Default is '1'. + - 'revealCursor': If 'true' reveals the cursor if it is outside view port. + +`revealLine` - Reveal the given line at the given logical position + +- _Reveal line argument object_ + + Property-value pairs that can be passed through this argument: + + - 'lineNumber': A mandatory line number value. + - 'at': Logical position at which line has to be revealed . + ``` + 'top', 'center', 'bottom' + ``` + +`editor.unfold` - Unfold the content in the editor + +- _Unfold editor argument_ + + Property-value pairs that can be passed through this argument: + + - 'levels': Number of levels to unfold. If not set, defaults to 1. + - 'direction': If 'up', unfold given number of levels up otherwise unfolds down. + - 'selectionLines': The start lines (0-based) of the editor selections to apply the unfold action to. If not set, the active selection(s) will be used. + +`editor.fold` - Fold the content in the editor + +- _Fold editor argument_ + + Property-value pairs that can be passed through this argument: + + - 'levels': Number of levels to fold. Defaults to 1. + - 'direction': If 'up', folds given number of levels up otherwise folds down. + - 'selectionLines': The start lines (0-based) of the editor selections to apply the fold action to. If not set, the active selection(s) will be used. + +`editor.action.showReferences` - Show references at a position in a file + +- _uri_ - The text document in which to show references +- _position_ - The position at which to show +- _locations_ - An array of locations. + +`moveActiveEditor` - Move the active editor by tabs or groups + +- _Active editor move argument_ + + Argument Properties: + + - 'to': String value providing where to move. + - 'by': String value providing the unit for move (by tab or by group). + - 'value': Number value providing how many positions or an absolute position to move. + +## Simple commands + +Simple commands that do not require parameters can be found in the Keyboard Shortcuts list in the default `keybindings.json` file. The unbound commands are listed in a comment block at the bottom of the file. + +To review `keybindings.json`: + +Windows, Linux: **File** > **Preferences** > **Keyboard Shortcuts** > `keybindings.json` link + +macOS: +**Code** > **Preferences** > **Keyboard Shortcuts** > `keybindings.json` link diff --git a/api/references/contribution-points.md b/api/references/contribution-points.md new file mode 100644 index 0000000000000000000000000000000000000000..6ba8cca059d0f3f2ab1036569777b5f419babc51 --- /dev/null +++ b/api/references/contribution-points.md @@ -0,0 +1,715 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 2F27A240-8E36-4CC2-973C-9A1D8069F83F +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: To extend Visual Studio Code, your extension (plug-in) declares which of the various Contribution Points it is using in its package.json Extension Manifest file. +--- + +# Contribution Points + +**Contribution Points** are a set of JSON declarations that you make in the `contributes` field of the `package.json` [Extension Manifest](/api/references/extension-manifest). Your extension registers **Contribution Points** to extend various functionalities within Visual Studio Code. Here is a list of all available **Contribution Points**: + +- [`configuration`](/api/references/contribution-points#contributes.configuration) +- [`commands`](/api/references/contribution-points#contributes.commands) +- [`menus`](/api/references/contribution-points#contributes.menus) +- [`keybindings`](/api/references/contribution-points#contributes.keybindings) +- [`languages`](/api/references/contribution-points#contributes.languages) +- [`debuggers`](/api/references/contribution-points#contributes.debuggers) +- [`breakpoints`](/api/references/contribution-points#contributes.breakpoints) +- [`grammars`](/api/references/contribution-points#contributes.grammars) +- [`themes`](/api/references/contribution-points#contributes.themes) +- [`snippets`](/api/references/contribution-points#contributes.snippets) +- [`jsonValidation`](/api/references/contribution-points#contributes.jsonValidation) +- [`views`](/api/references/contribution-points#contributes.views) +- [`viewsContainers`](/api/references/contribution-points#contributes.viewsContainers) +- [`problemMatchers`](/api/references/contribution-points#contributes.problemMatchers) +- [`problemPatterns`](/api/references/contribution-points#contributes.problemPatterns) +- [`taskDefinitions`](/api/references/contribution-points#contributes.taskDefinitions) +- [`colors`](/api/references/contribution-points#contributes.colors) +- [`typescriptServerPlugins`](/api/references/contribution-points#contributes.typescriptServerPlugins) + +## contributes.configuration + +Contribute configuration keys that will be exposed to the user. The user will be able to set these configuration options either from User Settings or from the Workspace Settings. + +When contributing configuration keys, a JSON schema describing these keys is actually contributed. This ensures the user gets great tooling support when authoring VS Code settings files. + +You can read these values from your extension using `vscode.workspace.getConfiguration('myExtension')`. + +> **Note:** If you use `markdownDescription` instead of `description`, your setting description will be rendered as Markdown in the settings UI. + +### Example + +```json +"contributes": { + "configuration": { + "type": "object", + "title": "TypeScript configuration", + "properties": { + "typescript.useCodeSnippetsOnMethodSuggest": { + "type": "boolean", + "default": false, + "description": "Complete functions with their parameter signature." + }, + "typescript.tsdk": { + "type": ["string", "null"], + "default": null, + "description": "Specifies the folder path containing the tsserver and lib*.d.ts files to use." + } + } + } +} +``` + +![configuration extension point example](images/contribution-points/configuration.png) + +## contributes.configurationDefaults + +Contribute default language specific editor configurations. This will override default editor configurations for the provided language. + +The following example contributes default editor configurations for the `markdown` language: + +### Example + +```json +"contributes": { + "configurationDefaults": { + "[markdown]": { + "editor.wordWrap": "on", + "editor.quickSuggestions": false + } + } +} +``` + +## contributes.commands + +Contribute an entry consisting of a title and a command to invoke to the **Command Palette** (`kb(workbench.action.showCommands)`). You can also optionally define a `category` string which will prefix the command title and allow easy grouping within the **Command Palette** drop-down. + +> **Note:** When a command is invoked (from a key binding or from the **Command Palette**), VS Code will emit an activationEvent `onCommand:${command}`. + +### Example + +```json +"contributes": { + "commands": [{ + "command": "extension.sayHello", + "title": "Hello World", + "category": "Hello" + }] +} +``` + +![commands extension point example](images/contribution-points/commands.png) + +## contributes.menus + +Contribute a menu item for a command to the editor or Explorer. The menu item definition contains the command that should be invoked when selected and the condition under which the item should show. The latter is defined with the `when` clause which uses the key bindings [when clause contexts](/docs/getstarted/keybindings#_when-clause-contexts). + +In addition to the mandatory `command` property, an alternative command can be defined using the `alt`-property. It will be shown and invoked when pressing `kbstyle(Alt)` while opening a menu. + +Last, a `group`-property defines sorting and grouping of menu items. The `navigation` group is special as it will always be sorted to the top/beginning of a menu. + +Currently extension writers can contribute to: + +- The global Command Palette - `commandPalette` +- The Explorer context menu - `explorer/context` +- The editor context menu - `editor/context` +- The editor title menu bar - `editor/title` +- The editor title context menu - `editor/title/context` +- The debug callstack view context menu - `debug/callstack/context` +- The debug toolbar - `debug/toolbar` +- The [SCM title menu](/api/extension-guides/scm-provider#menus) - `scm/title` +- [SCM resource groups](/api/extension-guides/scm-provider#menus) menus - `scm/resourceGroup/context` +- [SCM resources](/api/extension-guides/scm-provider#menus) menus - `scm/resource/context` +- [SCM change title](/api/extension-guides/scm-provider#menus) menus - `scm/change/title` +- The [View title menu](/api/references/contribution-points#contributes.views) - `view/title` +- The [View item menu](/api/references/contribution-points#contributes.views) - `view/item/context` +- The macOS Touch Bar - `touchBar` + +> **Note:** When a command is invoked from a (context) menu, VS Code tries to infer the currently selected resource and passes that as a parameter when invoking the command. For instance, a menu item inside the Explorer is passed the URI of the selected resource and a menu item inside an editor is passed the URI of the document. + +In addition to a title, commands can also define icons which VS Code will show in the editor title menu bar. + +### Example + +```json +"contributes": { + "menus": { + "editor/title": [{ + "when": "resourceLangId == markdown", + "command": "markdown.showPreview", + "alt": "markdown.showPreviewToSide", + "group": "navigation" + }] + } +} +``` + +![menus extension point example](images/contribution-points/menus.png) + +### Context specific visibility of Command Palette menu items + +When registering commands in `package.json`, they will automatically be shown in the **Command Palette** (`kb(workbench.action.showCommands)`). To allow more control over command visibility, there is the `commandPalette` menu item. It allows you to define a `when` condition to control if a command should be visible in the **Command Palette** or not. + +The snippet below makes the 'Hello World' command only visible in the **Command Palette** when something is selected in the editor: + +```json +"commands": [{ + "command": "extension.sayHello", + "title": "Hello World" +}], +"menus": { + "commandPalette": [{ + "command": "extension.sayHello", + "when": "editorHasSelection" + }] +} +``` + +### Sorting of groups + +Menu items can be sorted into groups. They are sorted in lexicographical order with the following defaults/rules. +You can add menu items to these groups or add new groups of menu items in between, below, or above. + +The **editor context menu** has these default groups: + +- `navigation` - The `navigation` group comes first in all cases. +- `1_modification` - This group comes next and contains commands that modify your code. +- `9_cutcopypaste` - The second last default group with the basic editing commands. +- `z_commands` - The last default group with an entry to open the Command Palette. + +![Menu Group Sorting](images/contribution-points/groupSorting.png) + +The **explorer context menu** has these default groups: + +- `navigation` - Commands related to navigation across VS Code. This group comes first in all cases. +- `2_workspace` - Commands related to workspace manipulation. +- `3_compare` - Commands related to comparing files in the diff editor. +- `4_search` - Commands related to searching in the search view. +- `5_cutcopypaste` - Commands related to cutting, copying and pasting of files. +- `6_copypath` - Commands related to copying file paths. +- `7_modification` - Commands related to the modification of a files. + +The **editor tab context menu** has these default groups: + +- `1_close` - Commands related to closing editors. +- `3_preview` - Commands related to pinning editors. + +The **editor title menu** has these default groups: + +- `1_diff` - Commands related to working with diff editors. +- `3_open` - Commands related to opening editors. +- `5_close` - Commands related to closing editors. + +### Sorting inside groups + +The order inside a group depends on the title or an order-attribute. The group-local order of a menu item is specified by appending `@` to the group identifier as shown below: + +```json +"editor/title": [{ + "when": "editorHasSelection", + "command": "extension.Command", + "group": "myGroup@1" +}] +``` + +## contributes.keybindings + +Contribute a key binding rule defining what command should be invoked when the user presses a key combination. See the [Key Bindings](/docs/getstarted/keybindings) topic where key bindings are explained in detail. + +Contributing a key binding will cause the Default Keyboard Shortcuts to display your rule, and every UI representation of the command will now show the key binding you have added. And, of course, when the user presses the key combination the command will be invoked. + +> **Note:** Because VS Code runs on Windows, macOS and Linux, where modifiers differ, you can use "key" to set the default key combination and overwrite it with a specific platform. + +> **Note:** When a command is invoked (from a key binding or from the Command Palette), VS Code will emit an activationEvent `onCommand:${command}`. + +### Example + +Defining that `kbstyle(Ctrl+F1)` under Windows and Linux and `kbstyle(Cmd+F1)` under macOS trigger the `"extension.sayHello"` command: + +```json +"contributes": { + "keybindings": [{ + "command": "extension.sayHello", + "key": "ctrl+f1", + "mac": "cmd+f1", + "when": "editorTextFocus" + }] +} +``` + +![keybindings extension point example](images/contribution-points/keybindings.png) + +## contributes.languages + +Contribute definition of a language. This will introduce a new language or enrich the knowledge VS Code has about a language. + +The main effects of `contributes.languages` are: + +- Define a `languageId` that can be reused in other parts of VS Code API, such as `vscode.TextDocument.getLanguageId()` and the `onLanguage` Activation Events. + - You can contribute a human-readable using the `aliases` field. The first item in the list will be used as the human-readable label. +- Associate file name extensions, file name patterns, files that begin with a specific line (such as hashbang), mimetypes to that `languageId`. +- Contribute a set of [Declarative Language Features](/api/language-extensions/overview#declarative-language-features) for the contributed language. Learn more about the configurable editing features in the [Language Configuration Guide](/api/language-extensions/language-configuration-guide). + +### Example + +```json +... +"contributes": { + "languages": [{ + "id": "python", + "extensions": [ ".py" ], + "aliases": [ "Python", "py" ], + "filenames": [ ... ], + "firstLine": "^#!/.*\\bpython[0-9.-]*\\b", + "configuration": "./language-configuration.json" + }] +} +``` + +## contributes.debuggers + +Contribute a debugger to VS Code. A debugger contribution has the following properties: + +- `type` is a unique ID that is used to identify this debugger in a launch configuration. +- `label` is the user visible name of this debugger in the UI. +- `program` the path to the debug adapter that implements the VS Code debug protocol against the real debugger or runtime. +- `runtime` if the path to the debug adapter is not an executable but needs a runtime. +- `configurationAttributes` is the schema for launch configuration arguments specific to this debugger. +- `initialConfigurations` lists launch configurations that are used to populate an initial launch.json. +- `configurationSnippets` lists launch configurations that are available through IntelliSense when editing a launch.json. +- `variables` introduces substitution variables and binds them to commands implemented by the debugger extension. +- `languages` those languages for which the debug extension could be considered the "default debugger". +- `adapterExecutableCommand` the command ID where the debug adapters executable path and arguments are dynamically calculated. The command returns a structure with this format: + ```json + command: "", + args: [ "", "", ... ] + ``` + The attribute `command` must be a either an absolute path to an executable or a name of executable looked up via the PATH environment variable. The special value `node` will be mapped to VS Code's built-in node runtime without being looked up on the PATH. + +### Example + +```json +"contributes": { + "debuggers": [{ + "type": "node", + "label": "Node Debug", + + "program": "./out/node/nodeDebug.js", + "runtime": "node", + + "languages": ["javascript", "typescript", "javascriptreact", "typescriptreact"], + + "configurationAttributes": { + "launch": { + "required": [ "program" ], + "properties": { + "program": { + "type": "string", + "description": "The program to debug." + } + } + } + }, + + "initialConfigurations": [{ + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${workspaceFolder}/app.js" + }], + + "configurationSnippets": [ + { + "label": "Node.js: Attach Configuration", + "description": "A new configuration for attaching to a running node program.", + "body": { + "type": "node", + "request": "attach", + "name": "${2:Attach to Port}", + "port": 9229 + } + } + ], + + "variables": { + "PickProcess": "extension.node-debug.pickNodeProcess" + } + }] +} +``` + +For a full walkthrough on how to integrate a `debugger`, go to [Debugger Extension](/api/extension-guides/debugger-extension). + +## contributes.breakpoints + +Usually a debugger extension will also have a `contributes.breakpoints` entry where the extension lists the language file types for which setting breakpoints will be enabled. + +```json +"contributes": { + "breakpoints": [ + { + "language": "javascript" + }, + { + "language": "javascriptreact" + } + ] +} +``` + +## contributes.grammars + +Contribute a TextMate grammar to a language. You must provide the `language` this grammar applies to, the TextMate `scopeName` for the grammar and the file path. + +> **Note:** The file containing the grammar can be in JSON (filenames ending in .json) or in XML plist format (all other files). + +### Example + +```json +"contributes": { + "grammars": [{ + "language": "markdown", + "scopeName": "text.html.markdown", + "path": "./syntaxes/markdown.tmLanguage.json", + "embeddedLanguages": { + "meta.embedded.block.frontmatter": "yaml", + ... + } + }] +} +``` + +See the [Syntax Highlight Guide](/api/language-extensions/syntax-highlight-guide) to learn more about how to register TextMate grammars associated with a language to receive syntax highlighting. + +![grammars extension point example](images/contribution-points/grammars.png) + +## contributes.themes + +Contribute a TextMate theme to VS Code. You must specify a label, whether the theme is a dark theme or a light theme (such that the rest of VS Code changes to match your theme) and the path to the file (XML plist format). + +### Example + +```json +"contributes": { + "themes": [{ + "label": "Monokai", + "uiTheme": "vs-dark", + "path": "./themes/Monokai.tmTheme" + }] +} +``` + +![themes extension point example](images/contribution-points/themes.png) + +See the [Color Theme Guide](/api/extension-guides/color-theme) on how to create a Color Theme. + +## contributes.snippets + +Contribute snippets for a specific language. The `language` attribute is the [language identifier](/docs/languages/identifiers) and the `path` is the relative path to the snippet file, which defines snippets in the [VS Code snippet format](/docs/editor/userdefinedsnippets#_snippet-syntax). + +The example below shows adding snippets for the Go language. + +```json +"contributes": { + "snippets": [{ + "language": "go", + "path": "./snippets/go.json" + }] +} +``` + +## contributes.jsonValidation + +Contribute a validation schema for a specific type of `json` file. The `url` value can be either a local path to a schema file included in the extension or a remote server URL such as a [json schema store](http://schemastore.org/json). + +```json +"contributes": { + "jsonValidation": [{ + "fileMatch": ".jshintrc", + "url": "http://json.schemastore.org/jshintrc" + }] +} +``` + +## contributes.views + +Contribute a view to VS Code. You must specify an identifier and name for the view. You can contribute to following view containers: + +- `explorer`: Explorer view container in the Activity Bar +- `scm`: Source Control Management (SCM) view container in the Activity Bar +- `debug`: Debug view container in the Activity Bar +- `test`: Test view container in the Activity Bar +- [Custom view containers](#contributes.viewsContainers) contributed by Extensions. + +When the user opens the view, VS Code will then emit an activationEvent `onView:${viewId}` (e.g. `onView:nodeDependencies` for the example below). You can also control the visibility of the view by providing the `when` context value. + +```json +"contributes": { + "views": { + "explorer": [ + { + "id": "nodeDependencies", + "name": "Node Dependencies", + "when": "workspaceHasPackageJSON" + } + ] + } +} +``` + +![views extension point example](images/contribution-points/views.png) + +Extension writers should create a [TreeView](/api/references/vscode-api#TreeView) by providing a [data provider](/api/references/vscode-api#TreeDataProvider) through `createTreeView` API or register the [data provider](/api/references/vscode-api#TreeDataProvider) directly through `registerTreeDataProvider` API to populate data. Refer to examples [here](https://github.com/Microsoft/vscode-extension-samples/tree/master/tree-view-sample). + +## contributes.viewsContainers + +Contribute a view container into which [Custom views](#contributes.views) can be contributed. You must specify an identifier, title and an icon for the view container. At present, you can contribute them to the Activity Bar (`activitybar`) only. Below example shows how the `Package Explorer` view container is contributed to the Activity Bar and how views are contributed to it. + +```json +"contributes": { + "viewsContainers": { + "activitybar": [ + { + "id": "package-explorer", + "title": "Package Explorer", + "icon": "resources/package-explorer.svg" + } + ] + }, + "views": { + "package-explorer": [ + { + "id": "package-dependencies", + "name": "Dependencies" + }, + { + "id": "package-outline", + "name": "Outline" + } + ] + } +} +``` + +![Custom views container](images/contribution-points/custom-views-container.png) + +**Icon specifications** + +- `Size:` Icons are 28x28 centered on a 50x40 block. +- `Color:` Icons should use a single monochrome color. +- `Format:` It is recommended that icons be in SVG, though any image file type is accepted. +- `States:` All icons inherit the following state styles: + + | State | Opacity | + | ------- | ------- | + | Default | 60% | + | Hover | 100% | + | Active | 100% | + +## contributes.problemMatchers + +Contribute problem matcher patterns. These contributions work in both the output panel runner and in the terminal runner. Below is an example to contribute a problem matcher for the gcc compiler in an extension: + +```json +"contributes": { + "problemMatchers": [ + { + "name": "gcc", + "owner": "cpp", + "fileLocation": ["relative", "${workspaceFolder}"], + "pattern": { + "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$", + "file": 1, + "line": 2, + "column": 3, + "severity": 4, + "message": 5 + } + } + ] +} +``` + +This problem matcher can now be used in a `tasks.json` file via a name reference `$gcc`. An example looks like this: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "build", + "command": "gcc", + "args": ["-Wall", "helloWorld.c", "-o", "helloWorld"], + "problemMatcher": "$gcc" + } + ] +} +``` + +Also see: [Defining a Problem Matcher](/docs/editor/tasks#_defining-a-problem-matcher) + +## contributes.problemPatterns + +Contributes named problem patterns that can be used in problem matchers (see above). + +## contributes.taskDefinitions + +Contributes and defines an object literal structures that allows to uniquely identify a contributed task in the system. A task definition has at minimum a `type` property but it usually defines additional properties. For example a task definition for a task representing a script in a package.json file looks like this: + +```json +"taskDefinitions": [ + { + "type": "npm", + "required": [ + "script" + ], + "properties": { + "script": { + "type": "string", + "description": "The script to execute" + }, + "path": { + "type": "string", + "description": "The path to the package.json file. If omitted the package.json in the root of the workspace folder is used." + } + } + } +] +``` + +The task definition is defined using JSON schema syntax for the `required` and `properties` property. The `type` property defines the task type. If the above example: + +- `"type": "npm"` associates the task definition with the npm tasks +- `"required": [ "script" ]` defines that `script` attributes as mandatory. The `path` property is optional. +- `"properties"` : { ... }` defines the additional properties and their types. + +When the extension actually creates a Task, it needs to pass a `TaskDefinition` that conforms to the task definition contributed in the package.json file. For the `npm` example a task creation for the test script inside a package.json file looks like this: + +```ts +let task = new vscode.Task({ type: 'npm', script: 'test' }, ....); +``` + +## contributes.colors + +Contributes new themable colors. These colors can be used by the extension in editor decorators and in the status bar. Once defined, users can customize the color in the `workspace.colorCustomization` setting and user themes can set the color value. + +```json +"contributes": { + "colors": [{ + "id": "superstatus.error", + "description": "Color for error message in the status bar.", + "defaults": { + "dark": "errorForeground", + "light": "errorForeground", + "highContrast": "#010203" + } + }] +} +``` + +Color default values can be defined for light, dark and high contrast theme and can either be a reference to an existing color or a [Color Hex Value](/api/references/theme-color#color-formats). + +## contributes.typescriptServerPlugins + +Contributes [TypeScript server plugins](https://github.com/Microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin) that augment VS Code's JavaScript and TypeScript support: + +```json +"contributes": { + "typescriptServerPlugins": [ + { + "name": "typescript-styled-plugin" + } + ] +} +``` + +The above example extension contributes the [`typescript-styled-plugin`](https://github.com/Microsoft/typescript-styled-plugin) which adds styled-component IntelliSense for JavaScript and TypeScript. This plugin will be loaded from the extension and must be installed as a normal NPM `dependency` in the extension: + +```json +{ + "dependencies": { + "typescript-styled-plugin": "*" + } +} +``` + +TypeScript server plugins are loaded for all JavaScript and TypeScript files when the user is using VS Code's version of TypeScript. They are not activated if the user is using a workspace version of TypeScript. + +## contributes.resourceLabelFormatters + +Contributes resource label formatters that specify how to display URIs everywhere in the workbench. For example here's how an extension could contribute a formatter for URIs with scheme `remotehub`: + +```json +"contributes": { + "resourceLabelFormatters": [ + { + "scheme": "remotehub", + "formatting": { + "label": "${path}", + "separator": "/", + "workspaceSuffix": "GitHub" + } + } + ] +} +``` + +This means that all URIs that have a scheme `remotehub` will get rendered by showing only the `path` segment of the URI and the separator will be `/`. Workspaces which have the `remotehub` URI will have the GitHub suffix in their label. + +### Plugin configuration + +Extensions can send configuration data to contributed TypeScript plugins through an API provided by VS Code's built-in TypeScript extension: + +```ts +// In your VS Code extension + +export async function activate(context: vscode.ExtensionContext) { + // Get the TS extension + const tsExtension = vscode.extensions.getExtension('vscode.typescript-language-features'); + if (!tsExtension) { + return; + } + + await tsExtension.activate(); + + // Get the API from the TS extension + if (!tsExtension.exports || !tsExtension.exports.getAPI) { + return; + } + + const api = tsExtension.exports.getAPI(0); + if (!api) { + return; + } + + // Configure the 'my-typescript-plugin-id' plugin + api.configurePlugin('my-typescript-plugin-id', { + someValue: process.env['SOME_VALUE'] + }); +} +``` + +The TypeScript server plugin receives the configuration data through an `onConfigurationChanged` method: + +```ts +// In your TypeScript plugin + +import * as ts_module from 'typescript/lib/tsserverlibrary'; + +export = function init({ typescript }: { typescript: typeof ts_module }) { + return { + create(info: ts.server.PluginCreateInfo) { + // Create new language service + }, + onConfigurationChanged(config: any) { + // Receive configuration changes sent from VS Code + } + }; +}; +``` + +This API allows VS Code extensions to synchronize VS Code settings with a TypeScript server plugin, or dynamically change the behavior of a plugin. Take a look at the [TypeScript TSLint plugin](https://github.com/Microsoft/vscode-typescript-tslint-plugin/blob/master/src/index.ts) and [lit-html](https://github.com/mjbvz/vscode-lit-html/blob/master/src/index.ts) extensions to see how this API is used in practice. diff --git a/api/references/document-selector.md b/api/references/document-selector.md new file mode 100644 index 0000000000000000000000000000000000000000..b8334297c2305f3294a8c8d1d93c05e13a45c041 --- /dev/null +++ b/api/references/document-selector.md @@ -0,0 +1,98 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: f328d7e0-8982-4510-b7fb-975188eca502 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Visual Studio Code extensions can filter their features based on Document Selectors by language, file type, and location. +--- + +# Document Selectors + +Extensions can filter their features based on document selectors by language, file type, and location. This topic discusses document selectors, document schemes, and what extensions authors should be aware about. + +## Text documents not on disk + +Not all text documents are stored on disk, for example, newly created documents. Unless specified, a document selector applies to **all** document types. Use the [DocumentFilter](/api/references/vscode-api#DocumentFilter) `scheme` property to narrow down on certain schemes, for example `{ scheme: 'file', language: 'typescript' }` for TypeScript files that are stored on disk. + +## Document selectors + +The Visual Studio Code extension API combines language-specific features, like IntelliSense, with document selectors through the [DocumentSelector](/api/references/vscode-api#DocumentSelector) type. They are an easy mechanism to narrow down functionality to a specific language. + +The snippet below registers a [HoverProvider](/api/references/vscode-api#HoverProvider) for TypeScript files and the document selector is the `typescript` language identifier string. + +```ts +vscode.languages.registerHoverProvider('typescript', { + provideHover(doc: vscode.TextDocument) { + return new vscode.Hover('For *all* TypeScript documents.'); + } +}); +``` + +A document selector can be more than just a language identifier and more complex selectors can use a [DocumentFilter](/api/references/vscode-api#DocumentFilter) to filter based on the `scheme` and file location through a `pattern` path glob-pattern: + +```ts +vscode.languages.registerHoverProvider( + { pattern: '**/test/**' }, + { + provideHover(doc: vscode.TextDocument) { + return new vscode.Hover('For documents inside `test`-folders only'); + } + } +); +``` + +The next snippet uses the `scheme` filter and combines it with a language identifier. The `untitled` scheme is for new files that have not yet been saved to disk. + +```ts +vscode.languages.registerHoverProvider( + { scheme: 'untitled', language: 'typescript' }, + { + provideHover(doc: vscode.TextDocument) { + return new vscode.Hover('For new, unsaved TypeScript documents only'); + } + } +); +``` + +## Document scheme + +The `scheme` of a document is often overlooked but is an important piece of information. Most documents are saved on disk and extension authors typically assume they are working with a file on disk. For example with a simple `typescript` selector, the assumption is **TypeScript files on disk**. However, there are scenarios where that assumption is too lax and a more explicit selector like `{ scheme: 'file', language: 'typescript' }` should be used. + +The importance of this comes into play when features rely on reading/writing files from/to disk. Check out the snippet below: + +```ts +// 👎 too lax +vscode.languages.registerHoverProvider('typescript', { + provideHover(doc: vscode.TextDocument) { + const { size } = fs.statSync(doc.uri.fsPath); // ⚠️ what about 'untitled:/Untitled1.ts' or others? + return new vscode.Hover(`Size in bytes is ${size}`); + } +}); +``` + +The hover provider above wants to display the size of a document on disk but it fails to check whether the document is actually stored on disk. For example, it could be newly created and not yet saved. The correct way would be to tell VS Code that the provider can only work with files on disk. + +```ts +// 👍 only works with files on disk +vscode.languages.registerHoverProvider( + { scheme: 'file', language: 'typescript' }, + { + provideHover(doc: vscode.TextDocument) { + const { size } = fs.statSync(doc.uri.fsPath); + return new vscode.Hover(`Size in bytes is ${size}`); + } + } +); +``` + +## Summary + +Documents are usually stored on the file system, but not always: there are untitled documents, cached documents that Git uses, documents from remote sources like FTP, and so forth. If your feature relies on disk access, make sure to use a document selector with the `file` scheme. + +## Next steps + +To learn more about VS Code extensibility model, try these topic: + +- [Extension Manifest File](/api/references/extension-manifest) - VS Code package.json extension manifest file reference +- [Contribution Points](/api/references/contribution-points) - VS Code contribution points reference diff --git a/api/references/extension-manifest.md b/api/references/extension-manifest.md new file mode 100644 index 0000000000000000000000000000000000000000..e8a5af8cad5df199c8996fc5c10711769303f02e --- /dev/null +++ b/api/references/extension-manifest.md @@ -0,0 +1,315 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: C4F184A5-A804-4B0B-9EBA-AFE83B88EE49 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: At the core of Visual Studio Code's extensibility model is an extension (plug-in) manifest file where your extension declares its extension type(s), activation rules, and runtime resources. +--- + +# Extension Manifest + +Every Visual Studio Code extension needs a manifest file `package.json` at the root of the extension directory structure. + +## Fields + +| Name | Required | Type | Details | +| ------------------------------------------------------- | :------: | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | Y | `string` | The name of the extension - should be all lowercase with no spaces. | +| `version` | Y | `string` | [SemVer](https://semver.org/) compatible version. | +| `publisher` | Y | `string` | The [publisher name](/api/working-with-extensions/publishing-extension#publishers-and-personal-access-tokens) | +| `engines` | Y | `object` | An object containing at least the `vscode` key matching the versions of VS Code that the extension is [compatible](/api/working-with-extensions/publishing-extension#visual-studio-code-compatibility) with. Cannot be `*`. For example: `^0.10.5` indicates compatibility with a minimum VS Code version of `0.10.5`. | +| `license` | | `string` | Refer to [npm's documentation](https://docs.npmjs.com/files/package.json#license). If you do have a `LICENSE` file in the root of your extension, the value for `license` should be `"SEE LICENSE IN "`. | +| `displayName` | | `string` | The display name for the extension used in the Marketplace. | +| `description` | | `string` | A short description of what your extension is and does. | +| `categories` | | `string[]` | the categories you want to use for the extensions allowed values: `[Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs]` | +| `keywords` | | `array` | An array of **keywords** to make it easier to find the extension. These are included with other extension **Tags** on the Marketplace. This list is currently limited to 5 keywords. | +| `galleryBanner` | | `object` | Helps format the Marketplace header to match your icon. See details below. | +| `preview` | | `boolean` | Sets the extension to be flagged as a Preview in the Marketplace. | +| `main` | | `string` | The entry point to your extension. | +| [`contributes`](/api/references/contribution-points) | | `object` | An object describing the extension's [contributions](/api/references/contribution-points). | +| [`activationEvents`](/api/references/activation-events) | | `array` | An array of the [activation events](/api/references/activation-events) for this extension. | +| `badges` | | `array` | Array of [approved](/api/references/extension-manifest#approved-badges) badges to display in the sidebar of the Marketplace's extension page. Each badge is an object containing 3 properties: `url` for the badge's image URL, `href` for the link users will follow when clicking the badge and `description`. | +| `markdown` | | `string` | Controls the Markdown rendering engine used in the Marketplace. Either `github` (default) or `standard`. | +| `qna` | | `marketplace` (default), `string`, `false` | Controls the **Q & A** link in the Marketplace. Set to `marketplace` to enable the default Marketplace Q & A site. Set to a string to provide the URL of a custom Q & A site. Set to `false` to disable Q & A altogether. | +| `dependencies` | | `object` | Any runtime Node.js dependencies your extensions needs. Exactly the same as [npm's `dependencies`](https://docs.npmjs.com/files/package.json#dependencies). | +| `devDependencies` | | `object` | Any development Node.js dependencies your extension needs. Exactly the same as [npm's `devDependencies`](https://docs.npmjs.com/files/package.json#devdependencies). | +| `extensionPack` | | `array` | An array with the ids of extensions bundled with this extension. These other extensions will be installed when the primary extension is installed. The id of an extension is always `${publisher}.${name}`. For example: `vscode.csharp`. | +| `extensionDependencies` | | `array` | An array with the ids of extensions that this extension depends on. These other extensions will be installed when the primary extension is installed. The id of an extension is always `${publisher}.${name}`. For example: `vscode.csharp`. | +| `scripts` | | `object` | Exactly the same as [npm's `scripts`](https://docs.npmjs.com/misc/scripts) but with extra VS Code specific fields such as [vscode:prepublish](/api/working-with-extensions/publishing-extension#prepublish-step) or [vscode:uninstall](/api/references/extension-manifest#extension-uninstall-hook). | +| `icon` | | `string` | The path to the icon of at least 128x128 pixels (256x256 for Retina screens). | + +Also check [npm's `package.json` reference](https://docs.npmjs.com/files/package.json). + +## Example + +Here is a complete `package.json` + +```json +{ + "name": "wordcount", + "displayName": "Word Count", + "version": "0.1.0", + "publisher": "ms-vscode", + "description": "Markdown Word Count Example - reports out the number of words in a Markdown file.", + "author": { + "name": "seanmcbreen" + }, + "categories": ["Other"], + "icon": "images/icon.png", + "galleryBanner": { + "color": "#C80000", + "theme": "dark" + }, + "activationEvents": ["onLanguage:markdown"], + "engines": { + "vscode": "^1.0.0" + }, + "main": "./out/extension", + "scripts": { + "vscode:prepublish": "node ./node_modules/vscode/bin/compile", + "compile": "node ./node_modules/vscode/bin/compile -watch -p ./" + }, + "devDependencies": { + "vscode": "0.10.x", + "typescript": "^1.6.2" + }, + "license": "SEE LICENSE IN LICENSE.txt", + "bugs": { + "url": "https://github.com/Microsoft/vscode-wordcount/issues", + "email": "smcbreen@microsoft.com" + }, + "repository": { + "type": "git", + "url": "https://github.com/Microsoft/vscode-wordcount.git" + }, + "homepage": "https://github.com/Microsoft/vscode-wordcount/blob/master/README.md" +} +``` + +## Marketplace Presentation Tips + +Here are some tips and recommendations to make your extension look great when displayed on the [VS Code Marketplace](https://marketplace.visualstudio.com/VSCode). + +Always use the latest `vsce` so `npm install -g vsce` to make sure you have it. + +Have a `README.md` Markdown file in your extension's root folder and we will include the contents in the body of the extension details (on the Marketplace). You can provide relative path image links in the `README.md`. + +Here are a few examples: + +1. [Word Count](https://marketplace.visualstudio.com/items?itemName=ms-vscode.wordcount) +2. [MD Tools](https://marketplace.visualstudio.com/items/seanmcbreen.MDTools) + +Provide a good display name and description. This is important for the Marketplace and in product displays. These strings are also used for text search in VS Code and having relevant keywords will help a lot. + +```json + "displayName": "Word Count", + "description": "Markdown Word Count Example - reports out the number of words in a Markdown file.", +``` + +An Icon and a contrasting banner color looks great on the Marketplace page header. The `theme` attribute refers to the font to be used in the banner - `dark` or `light`. + +```json +{ + "icon": "images/icon.png", + "galleryBanner": { + "color": "#C80000", + "theme": "dark" + } +} +``` + +There are several optional links (`bugs`, `homepage`, `repository`) you can set and these are displayed under the **Resources** section of the Marketplace. + +```json +{ + "license": "SEE LICENSE IN LICENSE.txt", + "homepage": "https://github.com/Microsoft/vscode-wordcount/blob/master/README.md", + "bugs": { + "url": "https://github.com/Microsoft/vscode-wordcount/issues", + "email": "smcbreen@microsoft.com" + }, + "repository": { + "type": "git", + "url": "https://github.com/Microsoft/vscode-wordcount.git" + } +} +``` + +| Marketplace Resources link | package.json attribute | +| -------------------------- | ---------------------- | +| Issues | `bugs:url` | +| Repository | `repository:url` | +| Homepage | `homepage` | +| License | `license` | + +Set a `category` for your extension. Extensions in the same `category` are grouped together on the Marketplace which improves filtering and discovery. + +> **Note:** Only use the values that make sense for your extension. Allowed values are `[Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs]`. Use `Programming Languages` for general language features like syntax highlighting and code completions. The category `Language Packs` is reserved for display language extensions (for example, localized Bulgarian). + +```json +{ + "categories": ["Linters", "Programming Languages", "Other"] +} +``` + +> **Tip:** The [Extension Manifest Editor](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.extension-manifest-editor) extension lets you preview how your extension `README.md` and `package.json` metadata will look when published to the Marketplace. + +### Approved Badges + +Due to security concerns, we only allow badges from trusted services. + +We allow badges from the following URL prefixes: + +- api.bintray.com +- api.travis-ci.com +- api.travis-ci.org +- app.fossa.io +- badge.fury.io +- badge.waffle.io +- badgen.net +- badges.frapsoft.com +- badges.gitter.im +- badges.greenkeeper.io +- cdn.travis-ci.com +- cdn.travis-ci.org +- ci.appveyor.com +- cla.opensource.microsoft.com +- codacy.com +- codeclimate.com +- codecov.io +- coveralls.io +- david-dm.org +- deepscan.io +- gemnasium.com +- githost.io +- gitlab.com +- godoc.org +- goreportcard.com +- img.shields.io +- isitmaintained.com +- marketplace.visualstudio.com +- nodesecurity.io +- opencollective.com +- snyk.io +- travis-ci.com +- travis-ci.org +- vsmarketplacebadge.apphb.com +- www.bithound.io +- www.versioneye.com + +If you have other badges you would like to use, please open a Github [issue](https://github.com/Microsoft/vscode/issues) and we're happy to take a look. + +## Combining Extension Contributions + +The `yo code` generator lets you easily package TextMate themes, colorizers and snippets and create new extensions. When the generator is run, it creates a complete standalone extension package for each option. However, it is often more convenient to have a single extension which combines multiple contributions. For example, if you are adding support for a new language, you'd like to provide users with both the language definition with colorization and also snippets and perhaps even debugging support. + +To combine extension contributions, edit an existing extension manifest `package.json` and add the new contributions and associated files. + +Below is an extension manifest which includes a LaTex language definition (language identifier and file extensions), colorization (`grammar`), and snippets. + +```json +{ + "name": "language-latex", + "description": "LaTex Language Support", + "version": "0.0.1", + "publisher": "someone", + "engines": { + "vscode": "0.10.x" + }, + "categories": ["Programming Languages", "Snippets"], + "contributes": { + "languages": [ + { + "id": "latex", + "aliases": ["LaTeX", "latex"], + "extensions": [".tex"] + } + ], + "grammars": [ + { + "language": "latex", + "scopeName": "text.tex.latex", + "path": "./syntaxes/latex.tmLanguage.json" + } + ], + "snippets": [ + { + "language": "latex", + "path": "./snippets/snippets.json" + } + ] + } +} +``` + +Notice that the extension manifest `categories` attribute now includes both `Programming Languages` and `Snippets` for easy discovery and filtering on the Marketplace. + +> **Tip:** Make sure your merged contributions are using the same identifiers. In the example above, all three contributions are using "latex" as the language identifier. This lets VS Code know that the colorizer (`grammar`) and snippets are for the LaTeX language and will be active when editing LaTeX files. + +## Extension Packs + +You can bundle separate extensions together in **Extension Packs**. An Extension Pack is a set of extensions that will be installed together. This enables easily sharing your favorite extensions with other users or creating a set of extensions for a particular scenario like PHP development to help a PHP developer get started with VS Code quickly. + +An Extension Pack bundles other extensions using the `extensionPack` attribute inside the `package.json` file. + +For example, here is an Extension Pack for PHP that includes a debugger, language service, and formatter: + +```json +{ + "extensionPack": [ + "felixfbecker.php-debug", + "felixfbecker.php-intellisense", + "Kasik96.format-php" + ] +} +``` + +When installing an Extension Pack, VS Code will now also install its extension dependencies. + +Extension packs should be categorized in the `Extension Packs` Marketplace category: + +```json +{ + "categories": ["Extension Packs"] +} +``` + +To create an extension pack, you can use the `yo code` Yeoman generator and choose the **New Extension Pack** option. There is an option to seed the pack with the set of extensions you have currently installed in your VS Code instance. In this way, you can easily create an Extension Pack with your favorite extensions, publish it to the Marketplace, and share it with others. + +An Extension Pack should not have any functional dependencies with its bundled extensions and the bundled extensions should be manageable independent of the pack. If an extension has a dependency on another extension, that dependency should be declared with the `extensionDependencies` attribute. + +### Extension uninstall hook + +If your extension has some clean up to be done when it is uninstalled from VS Code, you can register a `node` script to the uninstall hook `vscode:uninstall` under `scripts` section in extension's package.json. + +```json +{ + "scripts": { + "vscode:uninstall": "node ./out/src/lifecycle" + } +} +``` + +This script gets executed when the extension is completely uninstalled from VS Code which is when VS Code is restarted (shutdown and start) after the extension is uninstalled. + +**Note**: Only Node.js scripts are supported. + +## Useful Node modules + +There are several Node.js modules available on npmjs to help with writing VS Code extensions. You can include these in your extension's `dependencies` section. + +- [vscode-nls](https://www.npmjs.com/package/vscode-nls) - Support for externalization and localization. +- [vscode-uri](https://www.npmjs.com/package/vscode-uri) - The URI implementation used by VS Code and its extensions. +- [jsonc-parser](https://www.npmjs.com/package/jsonc-parser) - A scanner and fault tolerant parser to process JSON with or without comments. +- [request-light](https://www.npmjs.com/package/request-light) - A light weight Node.js request library with proxy support +- [vscode-extension-telemetry](https://www.npmjs.com/package/vscode-extension-telemetry) - Consistent telemetry reporting for VS Code extensions. +- [vscode-languageclient](https://www.npmjs.com/package/vscode-languageclient) - Easily integrate language servers adhering to the [language server protocol](https://microsoft.github.io/language-server-protocol). + +## Next steps + +To learn more about VS Code extensibility model, try these topic: + +- [Contribution Points](/api/references/contribution-points) - VS Code contribution points reference +- [Activation Events](/api/references/activation-events) - VS Code activation events reference +- [Extension Marketplace](/docs/editor/extension-gallery) - Read more about the VS Code Extension Marketplace diff --git a/api/references/icons-in-labels.md b/api/references/icons-in-labels.md new file mode 100644 index 0000000000000000000000000000000000000000..16f955331b685fe120d763278041d2f593ba98cc --- /dev/null +++ b/api/references/icons-in-labels.md @@ -0,0 +1,1723 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 109a10fc-2d64-44b6-98ce-b8375d245776 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Octicon reference that lists all octicons supported in VS Code +--- + +# Icons in Labels + +You can use [Octicons](https://octicons.github.com/) in your extension using the [`StatusBarItem`](https://code.visualstudio.com/api/references/vscode-api#StatusBarItem) text and [`QuickPickItem`](https://code.visualstudio.com/api/references/vscode-api#QuickPickItem) label API. The syntax for adding an icon is: + +```ts +$(alert); +``` + +You can also embed text and use multiple icons: + +```ts +$(eye) $(heart) $(mark-github) GitHub +``` + +## Icon Listing + +Below are the full listings of the icons that ships with the product: + +### Table Listing + +
+ +| preview | name | +| ------------------------------------------------------ | ---------------------- | +| | alert | +| | archive | +| | arrow-both | +| | arrow-down | +| | arrow-left | +| | arrow-right | +| | arrow-small-down | +| | arrow-small-left | +| | arrow-small-right | +| | arrow-small-up | +| | arrow-up | +| | beaker | +| | bell | +| | bold | +| | book | +| | bookmark | +| | briefcase | +| | broadcast | +| | browser | +| | bug | +| | calendar | +| | check | +| | checklist | +| | chevron-down | +| | chevron-left | +| | chevron-right | +| | chevron-up | +| | circle-slash | +| | circuit-board | +| | clippy | +| | clock | +| | clone | +| | cloud-download | +| | cloud-upload | +| | code | +| | color-mode | +| | comment | +| | comment-discussion | +| | credit-card | +| | dash | +| | dashboard | +| | database | +| | desktop-download | +| | device-camera | +| | device-camera-video | +| | device-desktop | +| | device-mobile | +| | diff | +| | diff-added | +| | diff-ignored | +| | diff-modified | +| | diff-removed | +| | diff-renamed | +| | ellipsis | +| | eye | +| | eye-closed | +| | file | +| | file-add | +| | file-binary | +| | file-code | +| | file-directory | +| | file-directory-create | +| | file-media | +| | file-pdf | +| | file-submodule | +| | file-symlink-directory | +| | file-symlink-file | +| | file-text | +| | file-zip | +| | flame | +| | fold | +| | fold-down | +| | fold-up | +| | gear | +| | gift | +| | gist | +| | gist-fork | +| | gist-new | +| | gist-private | +| | gist-secret | +| | git-branch | +| | git-commit | +| | git-compare | +| | git-fork-private | +| | git-merge | +| | git-pull-request | +| | github-action | +| | globe | +| | grabber | +| | graph | +| | heart | +| | history | +| | home | +| | horizontal-rule | +| | hubot | +| | inbox | +| | info | +| | issue-closed | +| | issue-opened | +| | issue-reopened | +| | italic | +| | jersey | +| | kebab-horizontal | +| | kebab-vertical | +| | key | +| | keyboard | +| | law | +| | light-bulb | +| | link | +| | link-external | +| | list-ordered | +| | list-unordered | +| | location | +| | lock | +| | log-in | +| | log-out | +| | logo-github | +| | mail | +| | mail-read | +| | mail-reply | +| | mark-github | +| | markdown | +| | megaphone | +| | mention | +| | microscope | +| | milestone | +| | mirror | +| | mirror-private | +| | mirror-public | +| | mortar-board | +| | mute | +| | no-newline | +| | note | +| | octoface | +| | organization | +| | organization-filled | +| | package | +| | paintcan | +| | pencil | +| | person | +| | person-filled | +| | pin | +| | play | +| | plug | +| | plus | +| | primitive-dot | +| | primitive-square | +| | project | +| | pulse | +| | question | +| | quote | +| | radio-tower | +| | remove-close | +| | reply | +| | repo | +| | repo-clone | +| | repo-create | +| | repo-force-push | +| | repo-forked | +| | repo-pull | +| | repo-push | +| | repo-sync | +| | report | +| | request-changes | +| | rocket | +| | rss | +| | ruby | +| | screen-full | +| | screen-normal | +| | search | +| | server | +| | settings | +| | shield | +| | sign-in | +| | sign-out | +| | smiley | +| | squirrel | +| | star | +| | stop | +| | sync | +| | tag | +| | tasklist | +| | telescope | +| | terminal | +| | text-size | +| | three-bars | +| | thumbsdown | +| | thumbsup | +| | tools | +| | trashcan | +| | triangle-down | +| | triangle-left | +| | triangle-right | +| | triangle-up | +| | unfold | +| | unmute | +| | unverified | +| | verified | +| | versions | +| | watch | +| | x | +| | zap | + +### Grid Listing + +
+ +
+ + + +
+ alert +
+ +
+ + + +
+ archive +
+ +
+ + + +
+ arrow-both +
+ +
+ + + +
+ arrow-down +
+ +
+ + + +
+ arrow-left +
+ +
+ + + +
+ arrow-right +
+ +
+ + + +
+ arrow-small-down +
+ +
+ + + +
+ arrow-small-left +
+ +
+ + + +
+ arrow-small-right +
+ +
+ + + +
+ arrow-small-up +
+ +
+ + + +
+ arrow-up +
+ +
+ + + +
+ beaker +
+ +
+ + + +
+ bell +
+ +
+ + + +
+ bold +
+ +
+ + + +
+ book +
+ +
+ + + +
+ bookmark +
+ +
+ + + +
+ briefcase +
+ +
+ + + +
+ broadcast +
+ +
+ + + +
+ browser +
+ +
+ + + +
+ bug +
+ +
+ + + +
+ calendar +
+ +
+ + + +
+ check +
+ +
+ + + +
+ checklist +
+ +
+ + + +
+ chevron-down +
+ +
+ + + +
+ chevron-left +
+ +
+ + + +
+ chevron-right +
+ +
+ + + +
+ chevron-up +
+ +
+ + + +
+ circle-slash +
+ +
+ + + +
+ circuit-board +
+ +
+ + + +
+ clippy +
+ +
+ + + +
+ clock +
+ +
+ + + +
+ cloud-download +
+ +
+ + + +
+ cloud-upload +
+ +
+ + + +
+ code +
+ +
+ + + +
+ color-mode +
+ +
+ + + +
+ comment-discussion +
+ +
+ + + +
+ comment +
+ +
+ + + +
+ credit-card +
+ +
+ + + +
+ dash +
+ +
+ + + +
+ dashboard +
+ +
+ + + +
+ database +
+ +
+ + + +
+ desktop-download +
+ +
+ + + +
+ device-camera-video +
+ +
+ + + +
+ device-camera +
+ +
+ + + +
+ device-desktop +
+ +
+ + + +
+ device-mobile +
+ +
+ + + +
+ diff-added +
+ +
+ + + +
+ diff-ignored +
+ +
+ + + +
+ diff-modified +
+ +
+ + + +
+ diff-removed +
+ +
+ + + +
+ diff-renamed +
+ +
+ + + +
+ diff +
+ +
+ + + +
+ ellipsis +
+ +
+ + + +
+ eye-closed +
+ +
+ + + +
+ eye +
+ +
+ + + +
+ file-binary +
+ +
+ + + +
+ file-code +
+ +
+ + + +
+ file-directory +
+ +
+ + + +
+ file-media +
+ +
+ + + +
+ file-pdf +
+ +
+ + + +
+ file-submodule +
+ +
+ + + +
+ file-symlink-directory +
+ +
+ + + +
+ file-symlink-file +
+ +
+ + + +
+ file-zip +
+ +
+ + + +
+ file +
+ +
+ + + +
+ flame +
+ +
+ + + +
+ fold-down +
+ +
+ + + +
+ fold-up +
+ +
+ + + +
+ fold +
+ +
+ + + +
+ gear +
+ +
+ + + +
+ gift +
+ +
+ + + +
+ gist-secret +
+ +
+ + + +
+ gist +
+ +
+ + + +
+ git-branch +
+ +
+ + + +
+ git-commit +
+ +
+ + + +
+ git-compare +
+ +
+ + + +
+ git-merge +
+ +
+ + + +
+ git-pull-request +
+ +
+ + + +
+ github-action +
+ +
+ + + +
+ globe +
+ +
+ + + +
+ grabber +
+ +
+ + + +
+ graph +
+ +
+ + + +
+ heart +
+ +
+ + + +
+ history +
+ +
+ + + +
+ home +
+ +
+ + + +
+ horizontal-rule +
+ +
+ + + +
+ hubot +
+ +
+ + + +
+ inbox +
+ +
+ + + +
+ info +
+ +
+ + + +
+ issue-closed +
+ +
+ + + +
+ issue-opened +
+ +
+ + + +
+ issue-reopened +
+ +
+ + + +
+ italic +
+ +
+ + + +
+ jersey +
+ +
+ + + +
+ kebab-horizontal +
+ +
+ + + +
+ kebab-vertical +
+ +
+ + + +
+ key +
+ +
+ + + +
+ keyboard +
+ +
+ + + +
+ law +
+ +
+ + + +
+ light-bulb +
+ +
+ + + +
+ link-external +
+ +
+ + + +
+ link +
+ +
+ + + +
+ list-ordered +
+ +
+ + + +
+ list-unordered +
+ +
+ + + +
+ location +
+ +
+ + + +
+ lock +
+ +
+ + + +
+ logo-github +
+ +
+ + + +
+ mail-read +
+ +
+ + + +
+ mail +
+ +
+ + + +
+ mark-github +
+ +
+ + + +
+ markdown +
+ +
+ + + +
+ megaphone +
+ +
+ + + +
+ mention +
+ +
+ + + +
+ milestone +
+ +
+ + + +
+ mirror +
+ +
+ + + +
+ mortar-board +
+ +
+ + + +
+ mute +
+ +
+ + + +
+ no-newline +
+ +
+ + + +
+ note +
+ +
+ + + +
+ octoface +
+ +
+ + + +
+ organization-filled +
+ +
+ + + +
+ organization-outline +
+ +
+ + + +
+ package +
+ +
+ + + +
+ paintcan +
+ +
+ + + +
+ pencil +
+ +
+ + + +
+ person-filled +
+ +
+ + + +
+ person-outline +
+ +
+ + + +
+ pin +
+ +
+ + + +
+ play +
+ +
+ + + +
+ plug +
+ +
+ + + +
+ plus +
+ +
+ + + +
+ primitive-dot +
+ +
+ + + +
+ primitive-square +
+ +
+ + + +
+ project +
+ +
+ + + +
+ pulse +
+ +
+ + + +
+ question +
+ +
+ + + +
+ quote +
+ +
+ + + +
+ radio-tower +
+ +
+ + + +
+ reply +
+ +
+ + + +
+ repo-clone +
+ +
+ + + +
+ repo-force-push +
+ +
+ + + +
+ repo-forked +
+ +
+ + + +
+ repo-pull +
+ +
+ + + +
+ repo-push +
+ +
+ + + +
+ repo +
+ +
+ + + +
+ report +
+ +
+ + + +
+ request-changes +
+ +
+ + + +
+ rocket +
+ +
+ + + +
+ rss +
+ +
+ + + +
+ ruby +
+ +
+ + + +
+ screen-full +
+ +
+ + + +
+ screen-normal +
+ +
+ + + +
+ search +
+ +
+ + + +
+ server +
+ +
+ + + +
+ settings +
+ +
+ + + +
+ shield +
+ +
+ + + +
+ sign-in +
+ +
+ + + +
+ sign-out +
+ +
+ + + +
+ smiley +
+ +
+ + + +
+ squirrel +
+ +
+ + + +
+ star +
+ +
+ + + +
+ stop +
+ +
+ + + +
+ sync +
+ +
+ + + +
+ tag +
+ +
+ + + +
+ tasklist +
+ +
+ + + +
+ telescope +
+ +
+ + + +
+ terminal +
+ +
+ + + +
+ text-size +
+ +
+ + + +
+ three-bars +
+ +
+ + + +
+ thumbsdown +
+ +
+ + + +
+ thumbsup +
+ +
+ + + +
+ tools +
+ +
+ + + +
+ trashcan +
+ +
+ + + +
+ triangle-down +
+ +
+ + + +
+ triangle-left +
+ +
+ + + +
+ triangle-right +
+ +
+ + + +
+ triangle-up +
+ +
+ + + +
+ unfold +
+ +
+ + + +
+ unmute +
+ +
+ + + +
+ unverified +
+ +
+ + + +
+ verified +
+ +
+ + + +
+ versions +
+ +
+ + + +
+ watch +
+ +
+ + + +
+ x +
+ +
+ + + +
+ zap +
+ +
+ +
diff --git a/api/references/images/contribution-points/commands.png b/api/references/images/contribution-points/commands.png new file mode 100644 index 0000000000000000000000000000000000000000..b1da93760cedeadd6d685226c7fec62e6a6fc5e8 Binary files /dev/null and b/api/references/images/contribution-points/commands.png differ diff --git a/api/references/images/contribution-points/configuration.png b/api/references/images/contribution-points/configuration.png new file mode 100644 index 0000000000000000000000000000000000000000..5f0474d93adfb89ea1fe397ea3b0e21b6659e1ea Binary files /dev/null and b/api/references/images/contribution-points/configuration.png differ diff --git a/api/references/images/contribution-points/custom-views-container.png b/api/references/images/contribution-points/custom-views-container.png new file mode 100644 index 0000000000000000000000000000000000000000..24e8f78146825be7a2eba67ad8cda23c43fab0f6 Binary files /dev/null and b/api/references/images/contribution-points/custom-views-container.png differ diff --git a/api/references/images/contribution-points/grammars.png b/api/references/images/contribution-points/grammars.png new file mode 100644 index 0000000000000000000000000000000000000000..c5596c37a5bf06ca66dcaf1f0d30bc190b7b4147 Binary files /dev/null and b/api/references/images/contribution-points/grammars.png differ diff --git a/api/references/images/contribution-points/groupSorting.png b/api/references/images/contribution-points/groupSorting.png new file mode 100644 index 0000000000000000000000000000000000000000..4c8a774dc38d937ea581713f17f9a3d946f9b559 Binary files /dev/null and b/api/references/images/contribution-points/groupSorting.png differ diff --git a/api/references/images/contribution-points/keybindings.png b/api/references/images/contribution-points/keybindings.png new file mode 100644 index 0000000000000000000000000000000000000000..9ea75d9dbb53a008aedc73f8fee6a718121a721c Binary files /dev/null and b/api/references/images/contribution-points/keybindings.png differ diff --git a/api/references/images/contribution-points/menus.png b/api/references/images/contribution-points/menus.png new file mode 100644 index 0000000000000000000000000000000000000000..3ba5cd80560b4e6427cfd4714066f372a9ca6f1f --- /dev/null +++ b/api/references/images/contribution-points/menus.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8474b234356c67d39ca5fc23bcd51a5408832c48a3f97a950f5d265276bf4bbe +size 223966 diff --git a/api/references/images/contribution-points/themes.png b/api/references/images/contribution-points/themes.png new file mode 100644 index 0000000000000000000000000000000000000000..a00de4ad8208eeda9121070590b52195fa3d200e Binary files /dev/null and b/api/references/images/contribution-points/themes.png differ diff --git a/api/references/images/contribution-points/views.png b/api/references/images/contribution-points/views.png new file mode 100644 index 0000000000000000000000000000000000000000..20f3adaf8e1cd612586aaf6cfc4af16fa49eb434 Binary files /dev/null and b/api/references/images/contribution-points/views.png differ diff --git a/api/references/images/theme-color/bracket-colors.png b/api/references/images/theme-color/bracket-colors.png new file mode 100644 index 0000000000000000000000000000000000000000..df73f59d5b92e1a28928d1faaca50abcaf441d8e Binary files /dev/null and b/api/references/images/theme-color/bracket-colors.png differ diff --git a/api/references/images/theme-color/button.png b/api/references/images/theme-color/button.png new file mode 100644 index 0000000000000000000000000000000000000000..940634c1b87a6341ca0b978a38ce40a20de1bd4f Binary files /dev/null and b/api/references/images/theme-color/button.png differ diff --git a/api/references/images/theme-color/codelens.png b/api/references/images/theme-color/codelens.png new file mode 100644 index 0000000000000000000000000000000000000000..e991e9c34e3833293ec3989189fdad808abd170b Binary files /dev/null and b/api/references/images/theme-color/codelens.png differ diff --git a/api/references/images/theme-color/dropdown.png b/api/references/images/theme-color/dropdown.png new file mode 100644 index 0000000000000000000000000000000000000000..2eb2f45c60a4072ba40c688813d0b1466d898d92 Binary files /dev/null and b/api/references/images/theme-color/dropdown.png differ diff --git a/api/references/images/theme-color/editorGroup-border.gif b/api/references/images/theme-color/editorGroup-border.gif new file mode 100644 index 0000000000000000000000000000000000000000..951016f5f0fad4c38d3627f25deff3a3ed435ea9 Binary files /dev/null and b/api/references/images/theme-color/editorGroup-border.gif differ diff --git a/api/references/images/theme-color/editorGroup-dropbackground.gif b/api/references/images/theme-color/editorGroup-dropbackground.gif new file mode 100644 index 0000000000000000000000000000000000000000..8cf045ca96c380f73c78685f379239a78a388f50 Binary files /dev/null and b/api/references/images/theme-color/editorGroup-dropbackground.gif differ diff --git a/api/references/images/theme-color/editorgroupheader-notabsbackground.gif b/api/references/images/theme-color/editorgroupheader-notabsbackground.gif new file mode 100644 index 0000000000000000000000000000000000000000..8e2cfeec6e9dfa46c2544b232e9c6389da2b7c0b Binary files /dev/null and b/api/references/images/theme-color/editorgroupheader-notabsbackground.gif differ diff --git a/api/references/images/theme-color/editorgroupheader-tabsbackground.gif b/api/references/images/theme-color/editorgroupheader-tabsbackground.gif new file mode 100644 index 0000000000000000000000000000000000000000..696e04ecc1074b1a489c958c7193b4dd3124e689 Binary files /dev/null and b/api/references/images/theme-color/editorgroupheader-tabsbackground.gif differ diff --git a/api/references/images/theme-color/editorgroupheader-tabsborder.gif b/api/references/images/theme-color/editorgroupheader-tabsborder.gif new file mode 100644 index 0000000000000000000000000000000000000000..8c2586cb987f6d19fcd27681e85e81ad00f98145 Binary files /dev/null and b/api/references/images/theme-color/editorgroupheader-tabsborder.gif differ diff --git a/api/references/images/theme-color/findmatches.png b/api/references/images/theme-color/findmatches.png new file mode 100644 index 0000000000000000000000000000000000000000..99c4ccaa9c6dcfff53115a7f5a7dec3c223891df Binary files /dev/null and b/api/references/images/theme-color/findmatches.png differ diff --git a/api/references/images/theme-color/hoverhighlight.png b/api/references/images/theme-color/hoverhighlight.png new file mode 100644 index 0000000000000000000000000000000000000000..a7539c136f36dcc7c587e324cfbe8829e6ce5b29 Binary files /dev/null and b/api/references/images/theme-color/hoverhighlight.png differ diff --git a/api/references/images/theme-color/input.png b/api/references/images/theme-color/input.png new file mode 100644 index 0000000000000000000000000000000000000000..74677b0705ddc7a9b0b8064a1a822d83cb5edf8e Binary files /dev/null and b/api/references/images/theme-color/input.png differ diff --git a/api/references/images/theme-color/line.png b/api/references/images/theme-color/line.png new file mode 100644 index 0000000000000000000000000000000000000000..6ce72f5cf4a498bc06807f7abfb58ee881f5e031 Binary files /dev/null and b/api/references/images/theme-color/line.png differ diff --git a/api/references/images/theme-color/link.png b/api/references/images/theme-color/link.png new file mode 100644 index 0000000000000000000000000000000000000000..53ade709e7b3294daf9c2564a76b0c90102cd255 Binary files /dev/null and b/api/references/images/theme-color/link.png differ diff --git a/api/references/images/theme-color/merge-ranges.png b/api/references/images/theme-color/merge-ranges.png new file mode 100644 index 0000000000000000000000000000000000000000..b49d981a40b7a33d1a424f2114a37c6990dba61e Binary files /dev/null and b/api/references/images/theme-color/merge-ranges.png differ diff --git a/api/references/images/theme-color/notification-center.png b/api/references/images/theme-color/notification-center.png new file mode 100644 index 0000000000000000000000000000000000000000..a90aed5604b29391e534309b8da46a2380a23937 Binary files /dev/null and b/api/references/images/theme-color/notification-center.png differ diff --git a/api/references/images/theme-color/notification-toast.png b/api/references/images/theme-color/notification-toast.png new file mode 100644 index 0000000000000000000000000000000000000000..9581be1a7a9018f9f403899d107442a83976316f Binary files /dev/null and b/api/references/images/theme-color/notification-toast.png differ diff --git a/api/references/images/theme-color/occurrences.png b/api/references/images/theme-color/occurrences.png new file mode 100644 index 0000000000000000000000000000000000000000..3f567d169229432656001cd94f36ff3fd133c9ee Binary files /dev/null and b/api/references/images/theme-color/occurrences.png differ diff --git a/api/references/images/theme-color/peek-view.png b/api/references/images/theme-color/peek-view.png new file mode 100644 index 0000000000000000000000000000000000000000..43c79ea1f76f61ab0dea4436c3d2598cf99e2423 Binary files /dev/null and b/api/references/images/theme-color/peek-view.png differ diff --git a/api/references/images/theme-color/rangehighlight.png b/api/references/images/theme-color/rangehighlight.png new file mode 100644 index 0000000000000000000000000000000000000000..9d84ab5ae137f05edad087b68f79123d9e8a09fe Binary files /dev/null and b/api/references/images/theme-color/rangehighlight.png differ diff --git a/api/references/images/theme-color/selectionhighlight.png b/api/references/images/theme-color/selectionhighlight.png new file mode 100644 index 0000000000000000000000000000000000000000..f6c1407c1554c9293a5cf5407e8618d49cfc4809 Binary files /dev/null and b/api/references/images/theme-color/selectionhighlight.png differ diff --git a/api/references/theme-color.md b/api/references/theme-color.md new file mode 100644 index 0000000000000000000000000000000000000000..9202cbdc5f135b9fe385ff3ab1ba7a1527b4429f --- /dev/null +++ b/api/references/theme-color.md @@ -0,0 +1,617 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 8e03996d-35e9-4e9f-a60e-50d0962231b8 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Theme Color reference that lists all themable colors in Visual Studio Code. +--- + +# Theme Color + +You can customize your active Visual Studio Code [color theme](/docs/getstarted/themes) with the `workbench.colorCustomizations` user [setting](/docs/getstarted/settings). + +```json +{ + "workbench.colorCustomizations": { + "activityBar.background": "#00AA00" + } +} +``` + +**Note**: If you want to use an existing color theme, see [Color Themes](/docs/getstarted/themes) where you'll learn how to set the active color theme through the **Preferences: Color Theme** dropdown (`kb(workbench.action.selectTheme)`). + +## Color formats + +Color values can be defined in the RGB color model with an alpha channel for transparency. As format, the following hexadecimal notations are supported: `#RGB`, `#RGBA`, `#RRGGBB` and `#RRGGBBAA`. R (red), G (green), B (blue), and A (alpha) are hexadecimal characters (0-9, a-f or A-F). The three-digit notation (`#RGB`) is a shorter version of the six-digit form (`#RRGGBB`) and the four-digit RGB notation (`#RGBA`) is a shorter version of the eight-digit form (`#RRGGBBAA`). For example `#e35f` is the same color as `#ee3355ff`. + +If no alpha value is defined, it defaults to `ff` (opaque, no transparency). If alpha is set to `00`, the color is fully transparent. + +Some colors should not be opaque in order to not cover other annotations. Check the color descriptions to see to which colors this applies. + +## Contrast colors + +The contrast colors are typically only set for high contrast themes. If set, they add an additional border around items across the UI to increase the contrast. + +- `contrastActiveBorder`: An extra border around active elements to separate them from others for greater contrast. +- `contrastBorder`: An extra border around elements to separate them from others for greater contrast. + +## Base colors + +- `focusBorder`: Overall border color for focused elements. This color is only used if not overridden by a component. +- `foreground`: Overall foreground color. This color is only used if not overridden by a component. +- `widget.shadow`: Shadow color of widgets such as Find/Replace inside the editor. +- `selection.background`: Background color of text selections in the workbench (for input fields or text areas, does not apply to selections within the editor and the terminal). +- `descriptionForeground`: Foreground color for description text providing additional information, for example for a label. +- `errorForeground`: Overall foreground color for error messages (this color is only used if not overridden by a component). + +## Text colors + +Colors inside a text document, such as the welcome page. + +- `textBlockQuote.background`: Background color for block quotes in text. +- `textBlockQuote.border`: Border color for block quotes in text. +- `textCodeBlock.background`: Background color for code blocks in text. +- `textLink.activeForeground`: Foreground color for links in text when clicked on and on mouse hover. +- `textLink.foreground`: Foreground color for links in text. +- `textPreformat.foreground`: Foreground color for preformatted text segments. +- `textSeparator.foreground`: Color for text separators. + +## Button control + +A set of colors for button widgets such as **Open Folder** button in the Explorer of a new window. + +![button control](images/theme-color/button.png) + +- `button.background`: Button background color. +- `button.foreground`: Button foreground color. +- `button.hoverBackground`: Button background color when hovering. + +## Dropdown control + +A set of colors for all Dropdown widgets such as in the Integrated Terminal or the Output panel. Note that the +Dropdown control is not used on macOS currently. + +![drop down control](images/theme-color/Dropdown.png) + +- `dropdown.background`: Dropdown background. +- `dropdown.listBackground`: Dropdown list background. +- `dropdown.border`: Dropdown border. +- `dropdown.foreground`: Dropdown foreground. + +## Input control + +Colors for input controls such as in the Search view or the Find/Replace dialog. + +![input control](images/theme-color/input.png) + +- `input.background`: Input box background. +- `input.border`: Input box border. +- `input.foreground`: Input box foreground. +- `input.placeholderForeground`: Input box foreground color for placeholder text. +- `inputOption.activeBorder`: Border color of activated options in input fields. +- `inputValidation.errorBackground`: Input validation background color for error severity. +- `inputValidation.errorForeground`: Input validation foreground color for error severity. +- `inputValidation.errorBorder`: Input validation border color for error severity. +- `inputValidation.infoBackground`: Input validation background color for information severity. +- `inputValidation.infoForeground`: Input validation foreground color for information severity. +- `inputValidation.infoBorder`: Input validation border color for information severity. +- `inputValidation.warningBackground`: Input validation background color for information warning. +- `inputValidation.warningForeground`: Input validation foreground color for warning severity. +- `inputValidation.warningBorder`: Input validation border color for warning severity. + +## Scrollbar control + +- `scrollbar.shadow`: Scrollbar slider shadow to indicate that the view is scrolled. +- `scrollbarSlider.activeBackground`: Scrollbar slider background color when clicked on. +- `scrollbarSlider.background`: Scrollbar slider background color. +- `scrollbarSlider.hoverBackground`: Scrollbar slider background color when hovering. + +## Badge + +Badges are small information labels, for example, search results count. + +- `badge.foreground`: Badge foreground color. +- `badge.background`: Badge background color. + +## Progress bar + +- `progressBar.background`: Background color of the progress bar shown for long running operations. + +## Lists and trees + +Colors for list and trees like the File Explorer. An active list/tree has keyboard focus, an inactive does not. + +- `list.activeSelectionBackground`: List/Tree background color for the selected item when the list/tree is active. +- `list.activeSelectionForeground`: List/Tree foreground color for the selected item when the list/tree is active. +- `list.dropBackground`: List/Tree drag and drop background when moving items around using the mouse. +- `list.focusBackground`: List/Tree background color for the focused item when the list/tree is active. +- `list.focusForeground`: List/Tree foreground color for the focused item when the list/tree is active. An active list/tree has keyboard focus, an inactive does not. +- `list.highlightForeground`: List/Tree foreground color of the match highlights when searching inside the list/tree. +- `list.hoverBackground`: List/Tree background when hovering over items using the mouse. +- `list.hoverForeground`: List/Tree foreground when hovering over items using the mouse. +- `list.inactiveSelectionBackground`: List/Tree background color for the selected item when the list/tree is inactive. +- `list.inactiveSelectionForeground`: List/Tree foreground color for the selected item when the list/tree is inactive. An active list/tree has keyboard focus, an inactive does not. +- `list.inactiveFocusBackground`: List background color for the focused item when the list is inactive. An active list has keyboard focus, an inactive does not. Currently only supported in lists. +- `list.invalidItemForeground`: List/Tree foreground color for invalid items, for example an unresolved root in explorer. +- `list.errorForeground`: Foreground color of list items containing errors. +- `list.warningForeground`: Foreground color of list items containing warnings. +- `listFilterWidget.background`: List/Tree Filter background color of typed text when searching inside the list/tree. +- `listFilterWidget.outline`: List/Tree Filter Widget's outline color of typed text when searching inside the list/tree. +- `listFilterWidget.noMatchesOutline`: List/Tree Filter Widget's outline color when no match is found of typed text when searching inside the list/tree. + +## Activity Bar + +The Activity Bar is displayed either on the far left or right of the workbench and allows fast switching between views of the Side Bar. + +- `activityBar.background`: Activity Bar background color. +- `activityBar.dropBackground`: Drag and drop feedback color for the Activity Bar items. +- `activityBar.foreground`: Activity bar foreground color (for example used for the icons). +- `activityBar.inactiveForeground`: Activity bar item foreground color when it is inactive. +- `activityBar.border`: Activity Bar border color with the Side Bar. +- `activityBarBadge.background`: Activity notification badge background color. +- `activityBarBadge.foreground`: Activity notification badge foreground color. + +## Side Bar + +The Side Bar contains views like the Explorer and Search. + +- `sideBar.background`: Side Bar background color. +- `sideBar.foreground`: Side Bar foreground color. The Side Bar is the container for views like Explorer and Search. +- `sideBar.border`: Side Bar border color on the side separating the editor. +- `sideBar.dropBackground`: Drag and drop feedback color for the side bar sections. The color should have transparency so that the side bar sections can still shine through. The side bar is the container for views like explorer and search. + +- `sideBarTitle.foreground`: Side Bar title foreground color. +- `sideBarSectionHeader.background`: Side Bar section header background color. +- `sideBarSectionHeader.foreground`: Side Bar section header foreground color. +- `sideBarSectionHeader.border`: Side bar section header border color. + +## Editor Groups & Tabs + +Editor Groups are the containers of editors. There can be many editor groups. A Tab is the container of an editor. Multiple Tabs can be opened in one editor group. + +- `editorGroup.border`: Color to separate multiple editor groups from each other. + + ![editorGroup.border](images/theme-color/editorGroup-border.gif) + +- `editorGroup.dropBackground`: Background color when dragging editors around. + + ![editorGroup.dropBackground](images/theme-color/editorGroup-dropbackground.gif) + +- `editorGroupHeader.noTabsBackground`: Background color of the editor group title header when Tabs are disabled (set `"workbench.editor.showTabs": false`). + + ![editorGroupHeader.noTabsBackground](images/theme-color/editorgroupheader-notabsbackground.gif) + +- `editorGroupHeader.tabsBackground`: Background color of the Tabs container. + + ![editorGroupHeader.tabsBackground](images/theme-color/editorgroupheader-tabsbackground.gif) + +- `editorGroupHeader.tabsBorder`: Border color of the editor group title header when tabs are enabled. + + ![editorGroupHeader.tabsBorder](images/theme-color/editorgroupheader-tabsborder.gif) + +- `editorGroup.emptyBackground`: Background color of an empty editor group. +- `editorGroup.focusedEmptyBorder`: Border color of an empty editor group that is focused. +- `tab.activeBackground`: Active Tab background color. +- `tab.activeForeground`: Active Tab foreground color in an active group. +- `tab.border`: Border to separate Tabs from each other. +- `tab.activeBorder`: Bottom border for the active tab. +- `tab.unfocusedActiveBorder`: Bottom border for the active tab in an inactive editor group. +- `tab.activeBorderTop`: Top border for the active tab. +- `tab.unfocusedActiveBorderTop`: Top border for the active tab in an inactive editor group +- `tab.inactiveBackground`: Inactive Tab background color. +- `tab.inactiveForeground`: Inactive Tab foreground color in an active group. +- `tab.unfocusedActiveForeground`: Active tab foreground color in an inactive editor group. +- `tab.unfocusedInactiveForeground`: Inactive tab foreground color in an inactive editor group. +- `tab.hoverBackground`: Tab background color when hovering +- `tab.unfocusedHoverBackground`: Tab background color in an unfocused group when hovering +- `tab.hoverBorder`: Border to highlight tabs when hovering +- `tab.unfocusedHoverBorder`: Border to highlight tabs in an unfocused group when hovering +- `tab.activeModifiedBorder`: Border on the top of modified (dirty) active tabs in an active group. +- `tab.inactiveModifiedBorder`: Border on the top of modified (dirty) inactive tabs in an active group. +- `tab.unfocusedActiveModifiedBorder`: Border on the top of modified (dirty) active tabs in an unfocused group. +- `tab.unfocusedInactiveModifiedBorder`: Border on the top of modified (dirty) inactive tabs in an unfocused group. +- `editorPane.background`: Background color of the editor pane visible on the left and right side of the centered editor layout. + +## Editor colors + +The most prominent editor colors are the token colors used for syntax highlighting and are based on the language grammar installed. These colors are defined by the Color Theme but can also be customized with the `editor.tokenColorCustomizations` setting. See [Customizing a Color Theme](/docs/getstarted/themes#_customizing-a-color-theme) for details on updating a Color Theme and the available token types. + +All other editor colors are listed here: + +- `editor.background`: Editor background color. +- `editor.foreground`: Editor default foreground color. +- `editorLineNumber.foreground`: Color of editor line numbers. +- `editorLineNumber.activeForeground`: Color of the active editor line number. +- `editorCursor.background`: The background color of the editor cursor. Allows customizing the color of a character overlapped by a block cursor. +- `editorCursor.foreground`: Color of the editor cursor. + +Selection colors are visible when selecting one or more characters. In addition to the selection also all regions with the same content are highlighted. + +![selection highlight](images/theme-color/selectionhighlight.png) + +- `editor.selectionBackground`: Color of the editor selection. +- `editor.selectionForeground`: Color of the selected text for high contrast. +- `editor.inactiveSelectionBackground`: Color of the selection in an inactive editor. The color must not be opaque so as not to hide underlying decorations. +- `editor.selectionHighlightBackground`: Color for regions with the same content as the selection. The color must not be opaque so as not to hide underlying decorations. +- `editor.selectionHighlightBorder`: Border color for regions with the same content as the selection. + +Word highlight colors are visible when the cursor is inside a symbol or a word. Depending on the language support available for the file type, all matching references and declarations are highlighted and read and write accesses get different colors. If document symbol language support is not available, this falls back to word highlighting. + +![occurrences](images/theme-color/occurrences.png) + +- `editor.wordHighlightBackground`: Background color of a symbol during read-access, for example when reading a variable. The color must not be opaque so as not to hide underlying decorations. +- `editor.wordHighlightBorder`: Border color of a symbol during read-access, for example when reading a variable. +- `editor.wordHighlightStrongBackground`: Background color of a symbol during write-access, for example when writing to a variable. The color must not be opaque so as not to hide underlying decorations. +- `editor.wordHighlightStrongBorder`: Border color of a symbol during write-access, for example when writing to a variable. + +Find colors depend on the current find string in the Find/Replace dialog. + +![Find matches](images/theme-color/findmatches.png) + +- `editor.findMatchBackground`: Color of the current search match. +- `editor.findMatchHighlightBackground`: Color of the other search matches. The color must not be opaque so as not to hide underlying decorations. +- `editor.findRangeHighlightBackground`: Color the range limiting the search (Enable 'Find in Selection' in the find widget). The color must not be opaque so as not to hide underlying decorations. +- `editor.findMatchBorder`: Border color of the current search match. +- `editor.findMatchHighlightBorder`: Border color of the other search matches. +- `editor.findRangeHighlightBorder`: Border color the range limiting the search (Enable 'Find in Selection' in the find widget). + +The hover highlight is shown behind the symbol for which a hover is shown. + +![Hover Highlight](images/theme-color/hoverhighlight.png) + +- `editor.hoverHighlightBackground`: Highlight below the word for which a hover is shown. The color must not be opaque so as not to hide underlying decorations. + +The current line is typically shown as either background highlight or a border (not both). + +![Line Highlight](images/theme-color/line.png) + +- `editor.lineHighlightBackground`: Background color for the highlight of line at the cursor position. +- `editor.lineHighlightBorder`: Background color for the border around the line at the cursor position. + +The link color is visible when clicking on a link. + +![Link](images/theme-color/link.png) + +- `editorLink.activeForeground`: Color of active links. + +The range highlight is visible when selecting a search result. + +![Range Highlight](images/theme-color/rangehighlight.png) + +- `editor.rangeHighlightBackground`: Background color of highlighted ranges, used by Quick Open, Symbol in File and Find features. The color must not be opaque so as not to hide underlying decorations. +- `editor.rangeHighlightBorder`: Background color of the border around highlighted ranges. + +To see the editor white spaces, enable **Toggle Render Whitespace**. + +- `editorWhitespace.foreground`: Color of whitespace characters in the editor. + +To see the editor indent guides, set `"editor.renderIndentGuides": true`. + +- `editorIndentGuide.background`: Color of the editor indentation guides. +- `editorIndentGuide.activeBackground`: Color of the active editor indentation guide. + +To see editor rulers, define their location with `"editor.rulers"` + +- `editorRuler.foreground`: Color of the editor rulers. + +CodeLens: + +![Code Lenses](images/theme-color/codelens.png) + +- `editorCodeLens.foreground`: Foreground color of an editor CodeLens. + +Bracket matches: + +![Bracket colors](images/theme-color/bracket-colors.png) + +- `editorBracketMatch.background`: Background color behind matching brackets. +- `editorBracketMatch.border`: Color for matching brackets boxes. + +Overview ruler: + +This ruler is located beneath the scroll bar on the right edge of the editor and gives an overview of the decorations in the editor. + +- `editorOverviewRuler.border`: Color of the overview ruler border. +- `editorOverviewRuler.findMatchForeground`: Overview ruler marker color for find matches. The color must not be opaque so as not to hide underlying decorations. +- `editorOverviewRuler.rangeHighlightForeground`: Overview ruler marker color for highlighted ranges, like by the Quick Open, Symbol in File and Find features. The color must not be opaque so as not to hide underlying decorations. +- `editorOverviewRuler.selectionHighlightForeground`: Overview ruler marker color for selection highlights. The color must not be opaque so as not to hide underlying decorations. +- `editorOverviewRuler.wordHighlightForeground`: Overview ruler marker color for symbol highlights. The color must not be opaque so as not to hide underlying decorations. +- `editorOverviewRuler.wordHighlightStrongForeground`: Overview ruler marker color for write-access symbol highlights. The color must not be opaque so as not to hide underlying decorations. +- `editorOverviewRuler.modifiedForeground`: Overview ruler marker color for modified content. +- `editorOverviewRuler.addedForeground`: Overview ruler marker color for added content. +- `editorOverviewRuler.deletedForeground`: Overview ruler marker color for deleted content. +- `editorOverviewRuler.errorForeground`: Overview ruler marker color for errors. +- `editorOverviewRuler.warningForeground`: Overview ruler marker color for warnings. +- `editorOverviewRuler.infoForeground`: Overview ruler marker color for infos. +- `editorOverviewRuler.bracketMatchForeground`: Overview ruler marker color for matching brackets. + +Errors and warnings: + +- `editorError.foreground`: Foreground color of error squiggles in the editor. +- `editorError.border`: Border color of error squiggles in the editor. +- `editorWarning.foreground`: Foreground color of warning squiggles in the editor. +- `editorWarning.border`: Border color of warning squiggles in the editor. +- `editorInfo.foreground`: Foreground color of info squiggles in the editor. +- `editorInfo.border`: Border color of info squiggles in the editor. +- `editorHint.foreground`: Foreground color of hints in the editor. +- `editorHint.border`: Border color of hints in the editor. + +Unused source code: + +- `editorUnnecessaryCode.border`: Border color of unnecessary (unused) source code in the editor. +- `editorUnnecessaryCode.opacity`: Opacity of unnecessary (unused) source code in the editor. For example, `"#000000c0"` will render the code with 75% opacity. For high contrast themes, use the `"editorUnnecessaryCode.border"` theme color to underline unnecessary code instead of fading it out. + +The gutter contains the glyph margins and the line numbers: + +- `editorGutter.background`: Background color of the editor gutter. The gutter contains the glyph margins and the line numbers. +- `editorGutter.modifiedBackground`: Editor gutter background color for lines that are modified. +- `editorGutter.addedBackground`: Editor gutter background color for lines that are added. +- `editorGutter.deletedBackground`: Editor gutter background color for lines that are deleted. + +## Diff editor colors + +For coloring inserted and removed text, use either a background or a border color but not both. + +- `diffEditor.insertedTextBackground`: Background color for text that got inserted. The color must not be opaque so as not to hide underlying decorations. +- `diffEditor.insertedTextBorder`: Outline color for the text that got inserted. +- `diffEditor.removedTextBackground`: Background color for text that got removed. The color must not be opaque so as not to hide underlying decorations. +- `diffEditor.removedTextBorder`: Outline color for text that got removed. +- `diffEditor.border`: Border color between the two text editors. + +## Editor widget colors + +The Editor widget is shown in front of the editor content. Examples are the Find/Replace dialog, the suggestion widget, and the editor hover. + +- `editorWidget.background`: Background color of editor widgets, such as Find/Replace. +- `editorWidget.border`: Border color of the editor widget unless the widget does not contain a border or defines its own border color. +- `editorWidget.resizeBorder`: Border color of the resize bar of editor widgets. The color is only used if the widget chooses to have a resize border and if the color is not overridden by a widget. + +- `editorSuggestWidget.background`: Background color of the suggestion widget. +- `editorSuggestWidget.border`: Border color of the suggestion widget. +- `editorSuggestWidget.foreground`: Foreground color of the suggestion widget. +- `editorSuggestWidget.highlightForeground`: Color of the match highlights in the suggestion widget. +- `editorSuggestWidget.selectedBackground`: Background color of the selected entry in the suggestion widget. + +- `editorHoverWidget.background`: Background color of the editor hover. +- `editorHoverWidget.border`: Border color of the editor hover. + +The Debug Exception widget is a peek view that shows in the editor when debug stops at an exception. + +- `debugExceptionWidget.background`: Exception widget background color. +- `debugExceptionWidget.border`: Exception widget border color. + +The editor marker view shows when navigating to errors and warnings in the editor (**Go to Next Error or Warning** command). + +- `editorMarkerNavigation.background`: Editor marker navigation widget background. +- `editorMarkerNavigationError.background`: Editor marker navigation widget error color. +- `editorMarkerNavigationWarning.background`: Editor marker navigation widget warning color. +- `editorMarkerNavigationInfo.background`: Editor marker navigation widget info color. + +## Peek view colors + +Peek views are used to show references and declarations as a view inside the editor. + +![Peek view](images/theme-color/peek-view.png) + +- `peekView.border`: Color of the peek view borders and arrow. +- `peekViewEditor.background`: Background color of the peek view editor. +- `peekViewEditorGutter.background`: Background color of the gutter in the peek view editor. +- `peekViewEditor.matchHighlightBackground`: Match highlight color in the peek view editor. +- `peekViewEditor.matchHighlightBorder`: Match highlight border color in the peek view editor. +- `peekViewResult.background`: Background color of the peek view result list. +- `peekViewResult.fileForeground`: Foreground color for file nodes in the peek view result list. +- `peekViewResult.lineForeground`: Foreground color for line nodes in the peek view result list. +- `peekViewResult.matchHighlightBackground`: Match highlight color in the peek view result list. +- `peekViewResult.selectionBackground`: Background color of the selected entry in the peek view result list. +- `peekViewResult.selectionForeground`: Foreground color of the selected entry in the peek view result list. +- `peekViewTitle.background`: Background color of the peek view title area. +- `peekViewTitleDescription.foreground`: Color of the peek view title info. +- `peekViewTitleLabel.foreground`: Color of the peek view title. + +## Merge conflicts + +Merge conflict decorations are shown when the editor contains special diff ranges. + +![Merge ranges](images/theme-color/merge-ranges.png) + +- `merge.currentHeaderBackground`: Current header background in inline merge conflicts. The color must not be opaque so as not to hide underlying decorations. +- `merge.currentContentBackground`: Current content background in inline merge conflicts. The color must not be opaque so as not to hide underlying decorations. +- `merge.incomingHeaderBackground`: Incoming header background in inline merge conflicts. The color must not be opaque so as not to hide underlying decorations. +- `merge.incomingContentBackground`: Incoming content background in inline merge conflicts. The color must not be opaque so as not to hide underlying decorations. +- `merge.border`: Border color on headers and the splitter in inline merge conflicts. +- `merge.commonContentBackground`: Common ancestor content background in inline merge-conflicts. The color must not be opaque so as not to hide underlying decorations. +- `merge.commonHeaderBackground`: Common ancestor header background in inline merge-conflicts. The color must not be opaque so as not to hide underlying decorations. +- `editorOverviewRuler.currentContentForeground`: Current overview ruler foreground for inline merge conflicts. +- `editorOverviewRuler.incomingContentForeground`: Incoming overview ruler foreground for inline merge conflicts. +- `editorOverviewRuler.commonContentForeground`: Common ancestor overview ruler foreground for inline merge conflicts. + +## Panel colors + +Panels are shown below the editor area and contain views like Output and Integrated Terminal. + +- `panel.background`: Panel background color. +- `panel.border`: Panel border color to separate the panel from the editor. +- `panel.dropBackground`: Drag and drop feedback color for the panel title items. The color should have transparency so that the panel entries can still shine through. +- `panelTitle.activeBorder`: Border color for the active panel title. +- `panelTitle.activeForeground`: Title color for the active panel. +- `panelTitle.inactiveForeground`: Title color for the inactive panel. + +## Status Bar colors + +The Status Bar is shown in the bottom of the workbench. + +- `statusBar.background`: Standard Status Bar background color. +- `statusBar.foreground`: Status Bar foreground color. +- `statusBar.border`: Status Bar border color separating the Status Bar and editor. +- `statusBar.debuggingBackground`: Status Bar background color when a program is being debugged. +- `statusBar.debuggingForeground`: Status Bar foreground color when a program is being debugged. +- `statusBar.debuggingBorder`: Status Bar border color separating the Status Bar and editor when a program is being debugged. +- `statusBar.noFolderForeground`: Status Bar foreground color when no folder is opened. +- `statusBar.noFolderBackground`: Status Bar background color when no folder is opened. +- `statusBar.noFolderBorder`: Status Bar border color separating the Status Bar and editor when no folder is opened. +- `statusBarItem.activeBackground`: Status Bar item background color when clicking. +- `statusBarItem.hoverBackground`: Status Bar item background color when hovering. +- `statusBarItem.prominentBackground`: Status Bar prominent items background color. Prominent items stand out from other Status Bar entries to indicate importance. Change mode `Toggle Tab Key Moves Focus` from command palette to see an example. +- `statusBarItem.prominentHoverBackground`: Status Bar prominent items background color when hovering. Prominent items stand out from other Status Bar entries to indicate importance. Change mode `Toggle Tab Key Moves Focus` from command palette to see an example. + +## Title Bar colors + +- `titleBar.activeBackground`: Title Bar background when the window is active. +- `titleBar.activeForeground`: Title Bar foreground when the window is active. +- `titleBar.inactiveBackground`: Title Bar background when the window is inactive. +- `titleBar.inactiveForeground`: Title Bar foreground when the window is inactive. +- `titleBar.border`: Title bar border color. + +## Menu Bar colors + +- `menubar.selectionForeground`: Foreground color of the selected menu item in the menubar. +- `menubar.selectionBackground`: Background color of the selected menu item in the menubar. +- `menubar.selectionBorder`: Border color of the selected menu item in the menubar. +- `menu.foreground`: Foreground color of menu items. +- `menu.background`: Background color of menu items. +- `menu.selectionForeground`: Foreground color of the selected menu item in menus. +- `menu.selectionBackground`: Background color of the selected menu item in menus. +- `menu.selectionBorder`: Border color of the selected menu item in menus. +- `menu.separatorBackground`: Color of a separator menu item in menus. + +## Notification colors + +**Note:** The colors below only apply for VS Code versions 1.21 and higher. + +Notification toasts slide up from the bottom-right of the workbench. + +![Notification Toasts](images/theme-color/notification-toast.png) + +Once opened in the Notification Center, they are displayed in a list with a header: + +![Notification Center](images/theme-color/notification-center.png) + +- `notificationCenter.border`: Notification Center border color. +- `notificationCenterHeader.foreground`: Notification Center header foreground color. +- `notificationCenterHeader.background`: Notification Center header background color. +- `notificationToast.border`: Notification toast border color. +- `notifications.foreground`: Notification foreground color. +- `notifications.background`: Notification background color. +- `notifications.border`: Notification border color separating from other notifications in the Notification Center. +- `notificationLink.foreground`: Notification links foreground color. + +If you target VS Code versions before the 1.21 (February 2018) release, these are the old (no longer supported) colors: + +- `notification.background` +- `notification.foreground` +- `notification.buttonBackground` +- `notification.buttonForeground` +- `notification.buttonHoverBackground` +- `notification.errorBackground` +- `notification.errorForeground` +- `notification.infoBackground` +- `notification.infoForeground` +- `notification.warningBackground` +- `notification.warningForeground` + +## Extensions + +- `extensionButton.prominentForeground`: Extension view button foreground color (for example **Install** button). +- `extensionButton.prominentBackground`: Extension view button background color. +- `extensionButton.prominentHoverBackground`: Extension view button background hover color. + +## Quick picker + +- `pickerGroup.border`: Quick picker (Quick Open) color for grouping borders. +- `pickerGroup.foreground`: Quick picker (Quick Open) color for grouping labels. + +## Integrated Terminal colors + +- `terminal.background`: The background of the Integrated Terminal's viewport. +- `terminal.border`: The color of the border that separates split panes within the terminal. This defaults to panel.border. +- `terminal.foreground`: The default foreground color of the Integrated Terminal. +- `terminal.ansiBlack`: 'Black' ANSI color in the terminal. +- `terminal.ansiBlue`: 'Blue' ANSI color in the terminal. +- `terminal.ansiBrightBlack`: 'BrightBlack' ANSI color in the terminal. +- `terminal.ansiBrightBlue`: 'BrightBlue' ANSI color in the terminal. +- `terminal.ansiBrightCyan`: 'BrightCyan' ANSI color in the terminal. +- `terminal.ansiBrightGreen`: 'BrightGreen' ANSI color in the terminal. +- `terminal.ansiBrightMagenta`: 'BrightMagenta' ANSI color in the terminal. +- `terminal.ansiBrightRed`: 'BrightRed' ANSI color in the terminal. +- `terminal.ansiBrightWhite`: 'BrightWhite' ANSI color in the terminal. +- `terminal.ansiBrightYellow`: 'BrightYellow' ANSI color in the terminal. +- `terminal.ansiCyan`: 'Cyan' ANSI color in the terminal. +- `terminal.ansiGreen`: 'Green' ANSI color in the terminal. +- `terminal.ansiMagenta`: 'Magenta' ANSI color in the terminal. +- `terminal.ansiRed`: 'Red' ANSI color in the terminal. +- `terminal.ansiWhite`: 'White' ANSI color in the terminal. +- `terminal.ansiYellow`: 'Yellow' ANSI color in the terminal. +- `terminal.selectionBackground`: The selection background color of the terminal. +- `terminalCursor.background`: The background color of the terminal cursor. Allows customizing the color of a character overlapped by a block cursor. +- `terminalCursor.foreground`: The foreground color of the terminal cursor. + +## Debug + +- `debugToolBar.background`: Debug toolbar background color. +- `debugToolBar.border`: Debug toolbar border color. +- `editor.stackFrameHighlightBackground`: Background color of the top stack frame highlight in the editor. +- `editor.focusedStackFrameHighlightBackground`: Background color of the focused stack frame highlight in the editor. + +## Welcome page + +- `welcomePage.background`: Background color for the Welcome page. +- `welcomePage.buttonBackground`: Background color for the buttons on the Welcome page. +- `welcomePage.buttonHoverBackground`: Hover background color for the buttons on the Welcome page. +- `walkThrough.embeddedEditorBackground`: Background color for the embedded editors on the Interactive Playground. + +## Git colors + +- `gitDecoration.addedResourceForeground`: Color for added Git resources. Used for file labels and the SCM viewlet. +- `gitDecoration.modifiedResourceForeground`: Color for modified Git resources. Used for file labels and the SCM viewlet. +- `gitDecoration.deletedResourceForeground`: Color for deleted Git resources. Used for file labels and the SCM viewlet. +- `gitDecoration.untrackedResourceForeground`: Color for untracked Git resources. Used for file labels and the SCM viewlet. +- `gitDecoration.ignoredResourceForeground`: Color for ignored Git resources. Used for file labels and the SCM viewlet. +- `gitDecoration.conflictingResourceForeground`: Color for conflicting Git resources. Used for file labels and the SCM viewlet. +- `gitDecoration.submoduleResourceForeground`: Color for submodule resources. + +## Settings Editor colors + +**Note:** These colors are for the GUI settings editor which can be opened with the `Preferences: Open Settings (UI)` command. + +- `settings.headerForeground`: The foreground color for a section header or active title. +- `settings.modifiedItemIndicator`: The line that indicates a modified setting. +- `settings.dropdownBackground`: Dropdown background. +- `settings.dropdownForeground`: Dropdown foreground. +- `settings.dropdownBorder`: Dropdown border. +- `settings.dropdownListBorder`: Dropdown list border. +- `settings.checkboxBackground`: Checkbox background. +- `settings.checkboxForeground`: Checkbox foreground. +- `settings.checkboxBorder`: Checkbox border. +- `settings.textInputBackground`: Text input box background. +- `settings.textInputForeground`: Text input box foreground. +- `settings.textInputBorder`: Text input box border. +- `settings.numberInputBackground`: Number input box background. +- `settings.numberInputForeground`: Number input box foreground. +- `settings.numberInputBorder`: Number input box border. + +## Breadcrumbs + +The theme colors for breadcrumbs navigation: + +- `breadcrumb.background`: Background color of breadcrumb. +- `breadcrumb.foreground`: Color of breadcrumb items. +- `breadcrumb.background`: Background color of breadcrumb items. +- `breadcrumb.focusForeground`: Color of focused breadcrumb items. +- `breadcrumb.activeSelectionForeground`: Color of selected breadcrumb items. +- `breadcrumbPicker.background`: Background color of breadcrumb item picker. + +## Snippets + +The theme colors for snippets: + +- `editor.snippetTabstopHighlightBackground`: Highlight background color of a snippet tabstop. +- `editor.snippetTabstopHighlightBorder`: Highlight border color of a snippet tabstop. +- `editor.snippetFinalTabstopHighlightBackground`: Highlight background color of the final tabstop of a snippet. +- `editor.snippetFinalTabstopHighlightBorder`: Highlight border color of the final tabstop of a snippet. + +Color ids can also be contributed by extensions through the [color contribution point](/api/references/contribution-points#contributes.colors). These colors also appear when using code complete in the `workbench.colorCustomizations` settings and the color theme definition file. Users can see what colors an extension defines in the [extension contributions](/docs/editor/extension-gallery#_extension-details) tab. + +## Extension colors + +Color ids can also be contributed by extensions through the [color contribution point](/api/references/contribution-points#contributes.colors). These colors also appear when using code complete in the `workbench.colorCustomizations` settings and the color theme definition file. Users can see what colors an extension defines in the [extension contributions](/docs/editor/extension-gallery#_extension-details) tab. diff --git a/api/references/vscode-api.md b/api/references/vscode-api.md new file mode 100644 index 0000000000000000000000000000000000000000..fc18308af9d86ca22e246a2a715a135c3d4c93e0 --- /dev/null +++ b/api/references/vscode-api.md @@ -0,0 +1,16362 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 8CEBCDF8-4F0A-4C81-A904-3DEA43480EA6 +DateApproved: 9/5/2018 + +VSCodeCommitHash: c6e592b2b5770e40a98cb9c2715a8ef89aec3d74 +VSCodeVersion: 1.30.0 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Visual Studio Code extensions (plug-in) API Reference. +--- + +# VS Code API + +**VS Code API** is a set of JavaScript APIs that you can invoke in your Visual Studio Code extension. This page lists all VS Code APIs available to extension authors. + +## API Patterns + +These are some of the common patterns we use in the VS Code API. + +### Promises + +The VS Code API represents asynchronous operations with [promises](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise). From extensions, __any__ type of promise can be returned, like ES6, WinJS, A+, etc. + +Being independent of a specific promise library is expressed in the API by the `Thenable`-type. `Thenable` represents the common denominator which is the [then](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/then) method. + +In most cases the use of promises is optional and when VS Code calls into an extension, it can handle the _result type_ as well as a `Thenable` of the _result type_. When the use of a promise is optional, the API indicates this by returning `or`-types. + +```typescript +provideNumber(): number | Thenable +``` + +### Cancellation Tokens + +Often operations are started on volatile state which changes before operations can finish. For instance, computing IntelliSense starts and the user continues to type making the result of that operation obsolete. + +APIs that are exposed to such behavior will get passed a `CancellationToken` on which you can check for cancellation (`isCancellationRequested`) or get notified when cancellation occurs (`onCancellationRequested`). The cancellation token is usually the last parameter of a function call and optional. + +### Disposables + +The VS Code API uses the [dispose pattern](https://en.wikipedia.org/wiki/Dispose_pattern) for resources that are obtained from VS Code. This applies to event listening, commands, interacting with the UI, and various language contributions. + +For instance, the `setStatusBarMessage(value: string)` function returns a `Disposable` which upon calling `dispose` removes the message again. + +### Events + +Events in the VS Code API are exposed as functions which you call with a listener-function to subscribe. Calls to subscribe return a `Disposable` which removes the event listener upon dispose. + +```javascript +var listener = function(event) { + console.log("It happened", event); +}; + +// start listening +var subscription = fsWatcher.onDidDelete(listener); + +// do more stuff + +subscription.dispose(); // stop listening +``` + +Names of events follow the `on[Will|Did]VerbNoun?` pattern. The name signals if the event is going to happen *(onWill)* or already happened *(onDid)*, what happened *(verb)*, and the context *(noun)* unless obvious from the context. + +An example from the VS Code API is `window.onDidChangeActiveTextEditor` which is an event fired when the active text editor *(noun)* has been (*onDid*) changed (*verb*). + +### Strict null + +The VS Code API uses the `undefined` and `null` TypeScript types where appropriate to support [strict null checking](https://github.com/Microsoft/TypeScript/pull/7140). + +## API Listing + +This listing is compiled from the [`vscode.d.ts`](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.d.ts) file from the VS Code repository. + +## commands + + + +

Namespace for dealing with commands. In short, a command is a function with a +unique identifier. The function is sometimes also called command handler.

+

Commands can be added to the editor using the registerCommand +and registerTextEditorCommand functions. Commands +can be executed manually or from a UI gesture. Those are:

+
    +
  • palette - Use the commands-section in package.json to make a command show in +the command palette.
    • +
  • keybinding - Use the keybindings-section in package.json to enable +keybindings +for your extension.
    • +
+

Commands from other extensions and from the editor itself are accessible to an extension. However, +when invoking an editor command not all argument types are supported.

+

This is a sample that registers a command handler and adds an entry for that command to the palette. First +register a command handler with the identifier extension.sayHello.

+ +
commands.registerCommand('extension.sayHello', () => {
+    window.showInformationMessage('Hello World!');
+});
+
+

Second, bind the command identifier to a title under which it will show in the palette (package.json).

+ +
{
+    "contributes": {
+        "commands": [{
+            "command": "extension.sayHello",
+            "title": "Hello World"
+        }]
+    }
+}
+
+
+ +#### Functions + + + +executeCommand<T>(command: string, ...rest: any[]): Thenable<T | undefined> +
+

Executes the command denoted by the given command identifier.

+
    +
  • Note 1: When executing an editor command not all types are allowed to +be passed as arguments. Allowed are the primitive types string, boolean, +number, undefined, and null, as well as Position, Range, Uri and Location.
    • +
  • Note 2: There are no restrictions when executing commands that have been contributed +by extensions.
    • +
+
+
+ + + + + + +
ParameterDescription
command: string

Identifier of the command to execute.

+
...rest: any[]

Parameters passed to the command function.

+
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the returned value of the given command. undefined when +the command handler function doesn't return anything.

+
+
+
+ + + +getCommands(filterInternal?: boolean): Thenable<string[]> +
+

Retrieve the list of all available commands. Commands starting an underscore are +treated as internal commands.

+
+
+ + + + + +
ParameterDescription
filterInternal?: boolean

Set true to not see internal commands (starting with an underscore)

+
ReturnsDescription
Thenable<string[]>

Thenable that resolves to a list of command ids.

+
+
+
+ + + +registerCommand(command: string, callback: (args: any[]) => any, thisArg?: any): Disposable +
+

Registers a command that can be invoked via a keyboard shortcut, +a menu item, an action, or directly.

+

Registering a command with an existing command identifier twice +will cause an error.

+
+
+ + + + + + + +
ParameterDescription
command: string

A unique identifier for the command.

+
callback: (args: any[]) => any

A command handler function.

+
thisArg?: any

The this context used when invoking the handler function.

+
ReturnsDescription
Disposable

Disposable which unregisters this command on disposal.

+
+
+
+ + + +registerTextEditorCommand(command: string, callback: (textEditor: TextEditor, edit: TextEditorEdit, args: any[]) => void, thisArg?: any): Disposable +
+

Registers a text editor command that can be invoked via a keyboard shortcut, +a menu item, an action, or directly.

+

Text editor commands are different from ordinary commands as +they only execute when there is an active editor when the command is called. Also, the +command handler of an editor command has access to the active editor and to an +edit-builder.

+
+
+ + + + + + + +
ParameterDescription
command: string

A unique identifier for the command.

+
callback: (textEditor: TextEditor, edit: TextEditorEdit, args: any[]) => void

A command handler function with access to an editor and an edit.

+
thisArg?: any

The this context used when invoking the handler function.

+
ReturnsDescription
Disposable

Disposable which unregisters this command on disposal.

+
+
+
+ +## debug + + + +

Namespace for debug functionality.

+
+ +#### Variables + + + +activeDebugConsole: DebugConsole +
+

The currently active debug console. +If no debug session is active, output sent to the debug console is not shown.

+
+
+ + + +activeDebugSession: DebugSession | undefined +
+

The currently active debug session or undefined. The active debug session is the one +represented by the debug action floating window or the one currently shown in the drop down menu of the debug action floating window. +If no debug session is active, the value is undefined.

+
+
+ + + +breakpoints: Breakpoint[] +
+

List of breakpoints.

+
+
+ +#### Events + + + +onDidChangeActiveDebugSession: Event<DebugSession | undefined> +
+

An event which fires when the active debug session +has changed. Note that the event also fires when the active debug session changes +to undefined.

+
+
+ + + +onDidChangeBreakpoints: Event<BreakpointsChangeEvent> +
+

An event that is emitted when the set of breakpoints is added, removed, or changed.

+
+
+ + + +onDidReceiveDebugSessionCustomEvent: Event<DebugSessionCustomEvent> +
+

An event which fires when a custom DAP event is received from the debug session.

+
+
+ + + +onDidStartDebugSession: Event<DebugSession> +
+

An event which fires when a new debug session has been started.

+
+
+ + + +onDidTerminateDebugSession: Event<DebugSession> +
+

An event which fires when a debug session has terminated.

+
+
+ +#### Functions + + + +addBreakpoints(breakpoints: Breakpoint[]): void +
+

Add breakpoints.

+
+
+ + + + + +
ParameterDescription
breakpoints: Breakpoint[]

The breakpoints to add.

+
ReturnsDescription
void
+
+
+ + + +registerDebugAdapterDescriptorFactory(debugType: string, factory: DebugAdapterDescriptorFactory): Disposable +
+

Register a debug adapter descriptor factory for a specific debug type. +An extension is only allowed to register a DebugAdapterDescriptorFactory for the debug type(s) defined by the extension. Otherwise an error is thrown. +Registering more than one DebugAdapterDescriptorFactory for a debug type results in an error.

+
+
+ + + + + + +
ParameterDescription
debugType: string

The debug type for which the factory is registered.

+
factory: DebugAdapterDescriptorFactory

The debug adapter descriptor factory to register.

+
ReturnsDescription
Disposable

A disposable that unregisters this factory when being disposed.

+
+
+
+ + + +registerDebugAdapterTrackerFactory(debugType: string, factory: DebugAdapterTrackerFactory): Disposable +
+

Register a debug adapter tracker factory for the given debug type.

+
+
+ + + + + + +
ParameterDescription
debugType: string

The debug type for which the factory is registered or '*' for matching all debug types.

+
factory: DebugAdapterTrackerFactory

The debug adapter tracker factory to register.

+
ReturnsDescription
Disposable

A disposable that unregisters this factory when being disposed.

+
+
+
+ + + +registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider): Disposable +
+

Register a debug configuration provider for a specific debug type. +More than one provider can be registered for the same type.

+
+
+ + + + + + +
ParameterDescription
debugType: string
provider: DebugConfigurationProvider

The debug configuration provider to register.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +removeBreakpoints(breakpoints: Breakpoint[]): void +
+

Remove breakpoints.

+
+
+ + + + + +
ParameterDescription
breakpoints: Breakpoint[]

The breakpoints to remove.

+
ReturnsDescription
void
+
+
+ + + +startDebugging(folder: WorkspaceFolder | undefined, nameOrConfiguration: string | DebugConfiguration): Thenable<boolean> +
+

Start debugging by using either a named launch or named compound configuration, +or by directly passing a DebugConfiguration. +The named configurations are looked up in '.vscode/launch.json' found in the given folder. +Before debugging starts, all unsaved files are saved and the launch configurations are brought up-to-date. +Folder specific variables used in the configuration (e.g. '${workspaceFolder}') are resolved against the given folder.

+
+
+ + + + + + +
ParameterDescription
folder: WorkspaceFolder | undefined

The workspace folder for looking up named configurations and resolving variables or undefined for a non-folder setup.

+
nameOrConfiguration: string | DebugConfiguration

Either the name of a debug or compound configuration or a DebugConfiguration object.

+
ReturnsDescription
Thenable<boolean>

A thenable that resolves when debugging could be successfully started.

+
+
+
+ +## env + + + +

Namespace describing the environment the editor runs in.

+
+ +#### Variables + + + +appName: string +
+

The application name of the editor, like 'VS Code'.

+
    +
  • readonly
    • +
+
+
+ + + +appRoot: string +
+

The application root folder from which the editor is running.

+
    +
  • readonly
    • +
+
+
+ + + +clipboard: Clipboard +
+

The system clipboard.

+
+
+ + + +language: string +
+

Represents the preferred user-language, like de-CH, fr, or en-US.

+
    +
  • readonly
    • +
+
+
+ + + +machineId: string +
+

A unique identifier for the computer.

+
    +
  • readonly
    • +
+
+
+ + + +sessionId: string +
+

A unique identifier for the current session. +Changes each time the editor is started.

+
    +
  • readonly
    • +
+
+
+ +## extensions + + + +

Namespace for dealing with installed extensions. Extensions are represented +by an extension-interface which enables reflection on them.

+

Extension writers can provide APIs to other extensions by returning their API public +surface from the activate-call.

+ +
export function activate(context: vscode.ExtensionContext) {
+    let api = {
+        sum(a, b) {
+            return a + b;
+        },
+        mul(a, b) {
+            return a * b;
+        }
+    };
+    // 'export' public api-surface
+    return api;
+}
+
+

When depending on the API of another extension add an extensionDependency-entry +to package.json, and use the getExtension-function +and the exports-property, like below:

+ +
let mathExt = extensions.getExtension('genius.math');
+let importedApi = mathExt.exports;
+
+console.log(importedApi.mul(42, 1));
+
+
+ +#### Variables + + + +all: Extension<any>[] +
+

All extensions currently known to the system.

+
+
+ +#### Functions + + + +getExtension(extensionId: string): Extension<any> | undefined +
+

Get an extension by its full identifier in the form of: publisher.name.

+
+
+ + + + + +
ParameterDescription
extensionId: string

An extension identifier.

+
ReturnsDescription
Extension<any> | undefined

An extension or undefined.

+
+
+
+ + + +getExtension<T>(extensionId: string): Extension<T> | undefined +
+

Get an extension its full identifier in the form of: publisher.name.

+
+
+ + + + + +
ParameterDescription
extensionId: string

An extension identifier.

+
ReturnsDescription
Extension<T> | undefined

An extension or undefined.

+
+
+
+ +## languages + + + +

Namespace for participating in language-specific editor features, +like IntelliSense, code actions, diagnostics etc.

+

Many programming languages exist and there is huge variety in syntaxes, semantics, and paradigms. Despite that, features +like automatic word-completion, code navigation, or code checking have become popular across different tools for different +programming languages.

+

The editor provides an API that makes it simple to provide such common features by having all UI and actions already in place and +by allowing you to participate by providing data only. For instance, to contribute a hover all you have to do is provide a function +that can be called with a TextDocument and a Position returning hover info. The rest, like tracking the +mouse, positioning the hover, keeping the hover stable etc. is taken care of by the editor.

+ +
languages.registerHoverProvider('javascript', {
+    provideHover(document, position, token) {
+        return new Hover('I am a hover!');
+    }
+});
+
+

Registration is done using a document selector which is either a language id, like javascript or +a more complex filter like { language: 'typescript', scheme: 'file' }. Matching a document against such +a selector will result in a score that is used to determine if and how a provider shall be used. When +scores are equal the provider that came last wins. For features that allow full arity, like hover, +the score is only checked to be >0, for other features, like IntelliSense the +score is used for determining the order in which providers are asked to participate.

+
+ +#### Events + + + +onDidChangeDiagnostics: Event<DiagnosticChangeEvent> +
+

An event which fires when the global set of diagnostics changes. This is +newly added and removed diagnostics.

+
+
+ +#### Functions + + + +createDiagnosticCollection(name?: string): DiagnosticCollection +
+

Create a diagnostics collection.

+
+
+ + + + + +
ParameterDescription
name?: string

The name of the collection.

+
ReturnsDescription
DiagnosticCollection

A new diagnostic collection.

+
+
+
+ + + +getDiagnostics(resource: Uri): Diagnostic[] +
+

Get all diagnostics for a given resource. Note that this includes diagnostics from +all extensions but not yet from the task framework.

+
+
+ + + + + +
ParameterDescription
resource: Uri

A resource

+
ReturnsDescription
Diagnostic[]

An array of diagnostics objects or an empty array.

+
+
+
+ + + +getDiagnostics(): [Uri, Diagnostic[]][] +
+

Get all diagnostics. Note that this includes diagnostics from +all extensions but not yet from the task framework.

+
+
+ + + +
ReturnsDescription
[Uri, Diagnostic[]][]

An array of uri-diagnostics tuples or an empty array.

+
+
+
+ + + +getLanguages(): Thenable<string[]> +
+

Return the identifiers of all known languages.

+
+
+ + + +
ReturnsDescription
Thenable<string[]>

Promise resolving to an array of identifier strings.

+
+
+
+ + + +match(selector: DocumentSelector, document: TextDocument): number +
+

Compute the match between a document selector and a document. Values +greater than zero mean the selector matches the document.

+

A match is computed according to these rules:

+
    +
  1. When DocumentSelector is an array, compute the match for each contained DocumentFilter or language identifier and take the maximum value.
    2. +
  2. A string will be desugared to become the language-part of a DocumentFilter, so "fooLang" is like { language: "fooLang" }.
    3. +
  3. A DocumentFilter will be matched against the document by comparing its parts with the document. The following rules apply:
      +
    1. When the DocumentFilter is empty ({}) the result is 0
      2. +
    2. When scheme, language, or pattern are defined but one doesn’t match, the result is 0
      3. +
    3. Matching against * gives a score of 5, matching via equality or via a glob-pattern gives a score of 10
      4. +
    4. The result is the maximum value of each match
      5. +
    +
    4. +
+

Samples:

+ +
// default document from disk (file-scheme)
+doc.uri; //'file:///my/file.js'
+doc.languageId; // 'javascript'
+match('javascript', doc); // 10;
+match({language: 'javascript'}, doc); // 10;
+match({language: 'javascript', scheme: 'file'}, doc); // 10;
+match('*', doc); // 5
+match('fooLang', doc); // 0
+match(['fooLang', '*'], doc); // 5
+
+// virtual document, e.g. from git-index
+doc.uri; // 'git:/my/file.js'
+doc.languageId; // 'javascript'
+match('javascript', doc); // 10;
+match({language: 'javascript', scheme: 'git'}, doc); // 10;
+match('*', doc); // 5
+
+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A document selector.

+
document: TextDocument

A text document.

+
ReturnsDescription
number

A number >0 when the selector matches and 0 when the selector does not match.

+
+
+
+ + + +registerCodeActionsProvider(selector: DocumentSelector, provider: CodeActionProvider, metadata?: CodeActionProviderMetadata): Disposable +
+

Register a code action provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: CodeActionProvider

A code action provider.

+
metadata?: CodeActionProviderMetadata

Metadata about the kind of code actions the provider providers.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerCodeLensProvider(selector: DocumentSelector, provider: CodeLensProvider): Disposable +
+

Register a code lens provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: CodeLensProvider

A code lens provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerColorProvider(selector: DocumentSelector, provider: DocumentColorProvider): Disposable +
+

Register a color provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: DocumentColorProvider

A color provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerCompletionItemProvider(selector: DocumentSelector, provider: CompletionItemProvider, ...triggerCharacters: string[]): Disposable +
+

Register a completion provider.

+

Multiple providers can be registered for a language. In that case providers are sorted +by their score and groups of equal score are sequentially asked for +completion items. The process stops when one or many providers of a group return a +result. A failing provider (rejected promise or exception) will not fail the whole +operation.

+
+
+ + + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: CompletionItemProvider

A completion provider.

+
...triggerCharacters: string[]

Trigger completion when the user types one of the characters, like . or :.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerDeclarationProvider(selector: DocumentSelector, provider: DeclarationProvider): Disposable +
+

Register a declaration provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: DeclarationProvider

A declaration provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerDefinitionProvider(selector: DocumentSelector, provider: DefinitionProvider): Disposable +
+

Register a definition provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: DefinitionProvider

A definition provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerDocumentFormattingEditProvider(selector: DocumentSelector, provider: DocumentFormattingEditProvider): Disposable +
+

Register a formatting provider for a document.

+

Multiple providers can be registered for a language. In that case providers are sorted +by their score and the best-matching provider is used. Failure +of the selected provider will cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: DocumentFormattingEditProvider

A document formatting edit provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerDocumentHighlightProvider(selector: DocumentSelector, provider: DocumentHighlightProvider): Disposable +
+

Register a document highlight provider.

+

Multiple providers can be registered for a language. In that case providers are sorted +by their score and groups sequentially asked for document highlights. +The process stops when a provider returns a non-falsy or non-failure result.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: DocumentHighlightProvider

A document highlight provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerDocumentLinkProvider(selector: DocumentSelector, provider: DocumentLinkProvider): Disposable +
+

Register a document link provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: DocumentLinkProvider

A document link provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerDocumentRangeFormattingEditProvider(selector: DocumentSelector, provider: DocumentRangeFormattingEditProvider): Disposable +
+

Register a formatting provider for a document range.

+

Note: A document range provider is also a document formatter +which means there is no need to register a document +formatter when also registering a range provider.

+

Multiple providers can be registered for a language. In that case providers are sorted +by their score and the best-matching provider is used. Failure +of the selected provider will cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: DocumentRangeFormattingEditProvider

A document range formatting edit provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerDocumentSymbolProvider(selector: DocumentSelector, provider: DocumentSymbolProvider, metaData?: DocumentSymbolProviderMetadata): Disposable +
+

Register a document symbol provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: DocumentSymbolProvider

A document symbol provider.

+
metaData?: DocumentSymbolProviderMetadata

metadata about the provider

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerFoldingRangeProvider(selector: DocumentSelector, provider: FoldingRangeProvider): Disposable +
+

Register a folding range provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. +If multiple folding ranges start at the same position, only the range of the first registered provider is used. +If a folding range overlaps with an other range that has a smaller position, it is also ignored.

+

A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: FoldingRangeProvider

A folding range provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerHoverProvider(selector: DocumentSelector, provider: HoverProvider): Disposable +
+

Register a hover provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: HoverProvider

A hover provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerImplementationProvider(selector: DocumentSelector, provider: ImplementationProvider): Disposable +
+

Register an implementation provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: ImplementationProvider

An implementation provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerOnTypeFormattingEditProvider(selector: DocumentSelector, provider: OnTypeFormattingEditProvider, firstTriggerCharacter: string, ...moreTriggerCharacter: string[]): Disposable +
+

Register a formatting provider that works on type. The provider is active when the user enables the setting editor.formatOnType.

+

Multiple providers can be registered for a language. In that case providers are sorted +by their score and the best-matching provider is used. Failure +of the selected provider will cause a failure of the whole operation.

+
+
+ + + + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: OnTypeFormattingEditProvider

An on type formatting edit provider.

+
firstTriggerCharacter: string

A character on which formatting should be triggered, like }.

+
...moreTriggerCharacter: string[]

More trigger characters.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerReferenceProvider(selector: DocumentSelector, provider: ReferenceProvider): Disposable +
+

Register a reference provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: ReferenceProvider

A reference provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerRenameProvider(selector: DocumentSelector, provider: RenameProvider): Disposable +
+

Register a rename provider.

+

Multiple providers can be registered for a language. In that case providers are sorted +by their score and the best-matching provider is used. Failure +of the selected provider will cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: RenameProvider

A rename provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, ...triggerCharacters: string[]): Disposable +
+

Register a signature help provider.

+

Multiple providers can be registered for a language. In that case providers are sorted +by their score and called sequentially until a provider returns a +valid result.

+
+
+ + + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: SignatureHelpProvider

A signature help provider.

+
...triggerCharacters: string[]

Trigger signature help when the user types one of the characters, like , or (.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, metadata: SignatureHelpProviderMetadata): Disposable +
+
+
+ + + + + + + +
ParameterDescription
selector: DocumentSelector
provider: SignatureHelpProvider
metadata: SignatureHelpProviderMetadata
ReturnsDescription
Disposable
+
+
+ + + +registerTypeDefinitionProvider(selector: DocumentSelector, provider: TypeDefinitionProvider): Disposable +
+

Register a type definition provider.

+

Multiple providers can be registered for a language. In that case providers are asked in +parallel and the results are merged. A failing provider (rejected promise or exception) will +not cause a failure of the whole operation.

+
+
+ + + + + + +
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

+
provider: TypeDefinitionProvider

A type definition provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerWorkspaceSymbolProvider(provider: WorkspaceSymbolProvider): Disposable +
+

Register a workspace symbol provider.

+

Multiple providers can be registered. In that case providers are asked in parallel and +the results are merged. A failing provider (rejected promise or exception) will not cause +a failure of the whole operation.

+
+
+ + + + + +
ParameterDescription
provider: WorkspaceSymbolProvider

A workspace symbol provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +setLanguageConfiguration(language: string, configuration: LanguageConfiguration): Disposable +
+

Set a language configuration for a language.

+
+
+ + + + + + +
ParameterDescription
language: string

A language identifier like typescript.

+
configuration: LanguageConfiguration

Language configuration.

+
ReturnsDescription
Disposable

A disposable that unsets this configuration.

+
+
+
+ + + +setTextDocumentLanguage(document: TextDocument, languageId: string): Thenable<TextDocument> +
+

Set (and change) the language that is associated +with the given document.

+

Note that calling this function will trigger the onDidCloseTextDocument event +followed by the onDidOpenTextDocument event.

+
+
+ + + + + + +
ParameterDescription
document: TextDocument

The document which language is to be changed

+
languageId: string

The new language identifier.

+
ReturnsDescription
Thenable<TextDocument>

A thenable that resolves with the updated document.

+
+
+
+ +## scm + + + +
+ +#### Variables + + + +inputBox: SourceControlInputBox +
+

The input box for the last source control +created by the extension.

+
    +
  • deprecated - Use SourceControl.inputBox instead
    • +
+
+
+ +#### Functions + + + +createSourceControl(id: string, label: string, rootUri?: Uri): SourceControl +
+

Creates a new source control instance.

+
+
+ + + + + + + +
ParameterDescription
id: string

An id for the source control. Something short, eg: git.

+
label: string

A human-readable string for the source control. Eg: Git.

+
rootUri?: Uri

An optional Uri of the root of the source control. Eg: Uri.parse(workspaceRoot).

+
ReturnsDescription
SourceControl

An instance of source control.

+
+
+
+ +## tasks + + + +

Namespace for tasks functionality.

+
+ +#### Variables + + + +taskExecutions: ReadonlyArray<TaskExecution> +
+

The currently active task executions or an empty array.

+
    +
  • readonly
    • +
+
+
+ +#### Events + + + +onDidEndTask: Event<TaskEndEvent> +
+

Fires when a task ends.

+
+
+ + + +onDidEndTaskProcess: Event<TaskProcessEndEvent> +
+

Fires when the underlying process has ended. +This event will not fire for tasks that don't +execute an underlying process.

+
+
+ + + +onDidStartTask: Event<TaskStartEvent> +
+

Fires when a task starts.

+
+
+ + + +onDidStartTaskProcess: Event<TaskProcessStartEvent> +
+

Fires when the underlying process has been started. +This event will not fire for tasks that don't +execute an underlying process.

+
+
+ +#### Functions + + + +executeTask(task: Task): Thenable<TaskExecution> +
+

Executes a task that is managed by VS Code. The returned +task execution can be used to terminate the task.

+
+
+ + + + + +
ParameterDescription
task: Task

the task to execute

+
ReturnsDescription
Thenable<TaskExecution>
+
+
+ + + +fetchTasks(filter?: TaskFilter): Thenable<Task[]> +
+

Fetches all tasks available in the systems. This includes tasks +from tasks.json files as well as tasks from task providers +contributed through extensions.

+
+
+ + + + + +
ParameterDescription
filter?: TaskFilter

a filter to filter the return tasks.

+
ReturnsDescription
Thenable<Task[]>
+
+
+ + + +registerTaskProvider(type: string, provider: TaskProvider): Disposable +
+

Register a task provider.

+
+
+ + + + + + +
ParameterDescription
type: string

The task kind type this provider is registered for.

+
provider: TaskProvider

A task provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ +## window + + + +

Namespace for dealing with the current window of the editor. That is visible +and active editors, as well as, UI elements to show messages, selections, and +asking for user input.

+
+ +#### Variables + + + +activeTerminal: Terminal | undefined +
+

The currently active terminal or undefined. The active terminal is the one that +currently has focus or most recently had focus.

+
+
+ + + +activeTextEditor: TextEditor | undefined +
+

The currently active editor or undefined. The active editor is the one +that currently has focus or, when none has focus, the one that has changed +input most recently.

+
+
+ + + +state: WindowState +
+

Represents the current window's state.

+
    +
  • readonly
    • +
+
+
+ + + +terminals: ReadonlyArray<Terminal> +
+

The currently opened terminals or an empty array.

+
+
+ + + +visibleTextEditors: TextEditor[] +
+

The currently visible editors or an empty array.

+
+
+ +#### Events + + + +onDidChangeActiveTerminal: Event<Terminal | undefined> +
+

An event which fires when the active terminal +has changed. Note that the event also fires when the active terminal changes +to undefined.

+
+
+ + + +onDidChangeActiveTextEditor: Event<TextEditor | undefined> +
+

An event which fires when the active editor +has changed. Note that the event also fires when the active editor changes +to undefined.

+
+
+ + + +onDidChangeTextEditorOptions: Event<TextEditorOptionsChangeEvent> +
+

An event which fires when the options of an editor have changed.

+
+
+ + + +onDidChangeTextEditorSelection: Event<TextEditorSelectionChangeEvent> +
+

An event which fires when the selection in an editor has changed.

+
+
+ + + +onDidChangeTextEditorViewColumn: Event<TextEditorViewColumnChangeEvent> +
+

An event which fires when the view column of an editor has changed.

+
+
+ + + +onDidChangeTextEditorVisibleRanges: Event<TextEditorVisibleRangesChangeEvent> +
+

An event which fires when the visible ranges of an editor has changed.

+
+
+ + + +onDidChangeVisibleTextEditors: Event<TextEditor[]> +
+

An event which fires when the array of visible editors +has changed.

+
+
+ + + +onDidChangeWindowState: Event<WindowState> +
+

An event which fires when the focus state of the current window +changes. The value of the event represents whether the window is focused.

+
+
+ + + +onDidCloseTerminal: Event<Terminal> +
+

An event which fires when a terminal is disposed.

+
+
+ + + +onDidOpenTerminal: Event<Terminal> +
+

An event which fires when a terminal has been created, either through the +createTerminal API or commands.

+
+
+ +#### Functions + + + +createInputBox(): InputBox +
+

Creates a InputBox to let the user enter some text input.

+

Note that in many cases the more convenient window.showInputBox +is easier to use. window.createInputBox should be used +when window.showInputBox does not offer the required flexibility.

+
+
+ + + +
ReturnsDescription
InputBox

A new InputBox.

+
+
+
+ + + +createOutputChannel(name: string): OutputChannel +
+

Creates a new output channel with the given name.

+
+
+ + + + + +
ParameterDescription
name: string

Human-readable string which will be used to represent the channel in the UI.

+
ReturnsDescription
OutputChannel
+
+
+ + + +createQuickPick<T extends QuickPickItem>(): QuickPick<T> +
+

Creates a QuickPick to let the user pick an item from a list +of items of type T.

+

Note that in many cases the more convenient window.showQuickPick +is easier to use. window.createQuickPick should be used +when window.showQuickPick does not offer the required flexibility.

+
+
+ + + +
ReturnsDescription
QuickPick<T>

A new QuickPick.

+
+
+
+ + + +createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem +
+

Creates a status bar item.

+
+
+ + + + + + +
ParameterDescription
alignment?: StatusBarAlignment

The alignment of the item.

+
priority?: number

The priority of the item. Higher values mean the item should be shown more to the left.

+
ReturnsDescription
StatusBarItem

A new status bar item.

+
+
+
+ + + +createTerminal(name?: string, shellPath?: string, shellArgs?: string[]): Terminal +
+

Creates a Terminal. The cwd of the terminal will be the workspace directory +if it exists, regardless of whether an explicit customStartPath setting exists.

+
+
+ + + + + + + +
ParameterDescription
name?: string

Optional human-readable string which will be used to represent the terminal in the UI.

+
shellPath?: string

Optional path to a custom shell executable to be used in the terminal.

+
shellArgs?: string[]

Optional args for the custom shell executable, this does not work on Windows (see #8429)

+
ReturnsDescription
Terminal

A new Terminal.

+
+
+
+ + + +createTerminal(options: TerminalOptions): Terminal +
+

Creates a Terminal. The cwd of the terminal will be the workspace directory +if it exists, regardless of whether an explicit customStartPath setting exists.

+
+
+ + + + + +
ParameterDescription
options: TerminalOptions

A TerminalOptions object describing the characteristics of the new terminal.

+
ReturnsDescription
Terminal

A new Terminal.

+
+
+
+ + + +createTextEditorDecorationType(options: DecorationRenderOptions): TextEditorDecorationType +
+

Create a TextEditorDecorationType that can be used to add decorations to text editors.

+
+
+ + + + + +
ParameterDescription
options: DecorationRenderOptions

Rendering options for the decoration type.

+
ReturnsDescription
TextEditorDecorationType

A new decoration type instance.

+
+
+
+ + + +createTreeView<T>(viewId: string, options: TreeViewOptions<T>): TreeView<T> +
+

Create a TreeView for the view contributed using the extension point views.

+
+
+ + + + + + +
ParameterDescription
viewId: string

Id of the view contributed using the extension point views.

+
options: TreeViewOptions<T>

Options for creating the TreeView

+
ReturnsDescription
TreeView<T>

a TreeView.

+
+
+
+ + + +createWebviewPanel(viewType: string, title: string, showOptions: ViewColumn | {preserveFocus: boolean, viewColumn: ViewColumn}, options?: WebviewPanelOptions & WebviewOptions): WebviewPanel +
+

Create and show a new webview panel.

+
+
+ + + + + + + + +
ParameterDescription
viewType: string

Identifies the type of the webview panel.

+
title: string

Title of the panel.

+
showOptions: ViewColumn | {preserveFocus: boolean, viewColumn: ViewColumn}

Where to show the webview in the editor. If preserveFocus is set, the new webview will not take focus.

+
options?: WebviewPanelOptions & WebviewOptions

Settings for the new panel.

+
ReturnsDescription
WebviewPanel

New webview panel.

+
+
+
+ + + +registerTreeDataProvider<T>(viewId: string, treeDataProvider: TreeDataProvider<T>): Disposable +
+

Register a TreeDataProvider for the view contributed using the extension point views. +This will allow you to contribute data to the TreeView and update if the data changes.

+

Note: To get access to the TreeView and perform operations on it, use createTreeView.

+
+
+ + + + + + +
ParameterDescription
viewId: string

Id of the view contributed using the extension point views.

+
treeDataProvider: TreeDataProvider<T>

A TreeDataProvider that provides tree data for the view

+
ReturnsDescription
Disposable
+
+
+ + + +registerUriHandler(handler: UriHandler): Disposable +
+

Registers a uri handler capable of handling system-wide uris. +In case there are multiple windows open, the topmost window will handle the uri. +A uri handler is scoped to the extension it is contributed from; it will only +be able to handle uris which are directed to the extension itself. A uri must respect +the following rules:

+
    +
  • The uri-scheme must be the product name;
    • +
  • The uri-authority must be the extension id (eg. my.extension);
    • +
  • The uri-path, -query and -fragment parts are arbitrary.
    • +
+

For example, if the my.extension extension registers a uri handler, it will only +be allowed to handle uris with the prefix product-name://my.extension.

+

An extension can only register a single uri handler in its entire activation lifetime.

+
    +
  • Note: There is an activation event onUri that fires when a uri directed for +the current extension is about to be handled.
    • +
+
+
+ + + + + +
ParameterDescription
handler: UriHandler

The uri handler to register for this extension.

+
ReturnsDescription
Disposable
+
+
+ + + +registerWebviewPanelSerializer(viewType: string, serializer: WebviewPanelSerializer): Disposable +
+

Registers a webview panel serializer.

+

Extensions that support reviving should have an "onWebviewPanel:viewType" activation event and +make sure that registerWebviewPanelSerializer is called during activation.

+

Only a single serializer may be registered at a time for a given viewType.

+
+
+ + + + + + +
ParameterDescription
viewType: string

Type of the webview panel that can be serialized.

+
serializer: WebviewPanelSerializer

Webview serializer.

+
ReturnsDescription
Disposable
+
+
+ + + +setStatusBarMessage(text: string, hideAfterTimeout: number): Disposable +
+

Set a message to the status bar. This is a short hand for the more powerful +status bar items.

+
+
+ + + + + + +
ParameterDescription
text: string

The message to show, supports icon substitution as in status bar items.

+
hideAfterTimeout: number

Timeout in milliseconds after which the message will be disposed.

+
ReturnsDescription
Disposable

A disposable which hides the status bar message.

+
+
+
+ + + +setStatusBarMessage(text: string, hideWhenDone: Thenable<any>): Disposable +
+

Set a message to the status bar. This is a short hand for the more powerful +status bar items.

+
+
+ + + + + + +
ParameterDescription
text: string

The message to show, supports icon substitution as in status bar items.

+
hideWhenDone: Thenable<any>

Thenable on which completion (resolve or reject) the message will be disposed.

+
ReturnsDescription
Disposable

A disposable which hides the status bar message.

+
+
+
+ + + +setStatusBarMessage(text: string): Disposable +
+

Set a message to the status bar. This is a short hand for the more powerful +status bar items.

+

Note that status bar messages stack and that they must be disposed when no +longer used.

+
+
+ + + + + +
ParameterDescription
text: string

The message to show, supports icon substitution as in status bar items.

+
ReturnsDescription
Disposable

A disposable which hides the status bar message.

+
+
+
+ + + +showErrorMessage(message: string, ...items: string[]): Thenable<string | undefined> +
+

Show an error message.

+ +
+
+ + + + + + +
ParameterDescription
message: string

The message to show.

+
...items: string[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showErrorMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined> +
+

Show an error message.

+ +
+
+ + + + + + + +
ParameterDescription
message: string

The message to show.

+
options: MessageOptions

Configures the behaviour of the message.

+
...items: string[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showErrorMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined> +
+

Show an error message.

+ +
+
+ + + + + + +
ParameterDescription
message: string

The message to show.

+
...items: T[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showErrorMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined> +
+

Show an error message.

+ +
+
+ + + + + + + +
ParameterDescription
message: string

The message to show.

+
options: MessageOptions

Configures the behaviour of the message.

+
...items: T[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showInformationMessage(message: string, ...items: string[]): Thenable<string | undefined> +
+

Show an information message to users. Optionally provide an array of items which will be presented as +clickable buttons.

+
+
+ + + + + + +
ParameterDescription
message: string

The message to show.

+
...items: string[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showInformationMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined> +
+

Show an information message to users. Optionally provide an array of items which will be presented as +clickable buttons.

+
+
+ + + + + + + +
ParameterDescription
message: string

The message to show.

+
options: MessageOptions

Configures the behaviour of the message.

+
...items: string[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showInformationMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined> +
+

Show an information message.

+ +
+
+ + + + + + +
ParameterDescription
message: string

The message to show.

+
...items: T[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showInformationMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined> +
+

Show an information message.

+ +
+
+ + + + + + + +
ParameterDescription
message: string

The message to show.

+
options: MessageOptions

Configures the behaviour of the message.

+
...items: T[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showInputBox(options?: InputBoxOptions, token?: CancellationToken): Thenable<string | undefined> +
+

Opens an input box to ask the user for input.

+

The returned value will be undefined if the input box was canceled (e.g. pressing ESC). Otherwise the +returned value will be the string typed by the user or an empty string if the user did not type +anything but dismissed the input box with OK.

+
+
+ + + + + + +
ParameterDescription
options?: InputBoxOptions

Configures the behavior of the input box.

+
token?: CancellationToken

A token that can be used to signal cancellation.

+
ReturnsDescription
Thenable<string | undefined>

A promise that resolves to a string the user provided or to undefined in case of dismissal.

+
+
+
+ + + +showOpenDialog(options: OpenDialogOptions): Thenable<Uri[] | undefined> +
+

Shows a file open dialog to the user which allows to select a file +for opening-purposes.

+
+
+ + + + + +
ParameterDescription
options: OpenDialogOptions

Options that control the dialog.

+
ReturnsDescription
Thenable<Uri[] | undefined>

A promise that resolves to the selected resources or undefined.

+
+
+
+ + + +showQuickPick(items: string[] | Thenable<string[]>, options: QuickPickOptions & {canPickMany: true}, token?: CancellationToken): Thenable<string[] | undefined> +
+

Shows a selection list allowing multiple selections.

+
+
+ + + + + + + +
ParameterDescription
items: string[] | Thenable<string[]>

An array of strings, or a promise that resolves to an array of strings.

+
options: QuickPickOptions & {canPickMany: true}

Configures the behavior of the selection list.

+
token?: CancellationToken

A token that can be used to signal cancellation.

+
ReturnsDescription
Thenable<string[] | undefined>

A promise that resolves to the selected items or undefined.

+
+
+
+ + + +showQuickPick(items: string[] | Thenable<string[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<string | undefined> +
+

Shows a selection list.

+
+
+ + + + + + + +
ParameterDescription
items: string[] | Thenable<string[]>

An array of strings, or a promise that resolves to an array of strings.

+
options?: QuickPickOptions

Configures the behavior of the selection list.

+
token?: CancellationToken

A token that can be used to signal cancellation.

+
ReturnsDescription
Thenable<string | undefined>

A promise that resolves to the selection or undefined.

+
+
+
+ + + +showQuickPick<T extends QuickPickItem>(items: T[] | Thenable<T[]>, options: QuickPickOptions & {canPickMany: true}, token?: CancellationToken): Thenable<T[] | undefined> +
+

Shows a selection list allowing multiple selections.

+
+
+ + + + + + + +
ParameterDescription
items: T[] | Thenable<T[]>

An array of items, or a promise that resolves to an array of items.

+
options: QuickPickOptions & {canPickMany: true}

Configures the behavior of the selection list.

+
token?: CancellationToken

A token that can be used to signal cancellation.

+
ReturnsDescription
Thenable<T[] | undefined>

A promise that resolves to the selected items or undefined.

+
+
+
+ + + +showQuickPick<T extends QuickPickItem>(items: T[] | Thenable<T[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<T | undefined> +
+

Shows a selection list.

+
+
+ + + + + + + +
ParameterDescription
items: T[] | Thenable<T[]>

An array of items, or a promise that resolves to an array of items.

+
options?: QuickPickOptions

Configures the behavior of the selection list.

+
token?: CancellationToken

A token that can be used to signal cancellation.

+
ReturnsDescription
Thenable<T | undefined>

A promise that resolves to the selected item or undefined.

+
+
+
+ + + +showSaveDialog(options: SaveDialogOptions): Thenable<Uri | undefined> +
+

Shows a file save dialog to the user which allows to select a file +for saving-purposes.

+
+
+ + + + + +
ParameterDescription
options: SaveDialogOptions

Options that control the dialog.

+
ReturnsDescription
Thenable<Uri | undefined>

A promise that resolves to the selected resource or undefined.

+
+
+
+ + + +showTextDocument(document: TextDocument, column?: ViewColumn, preserveFocus?: boolean): Thenable<TextEditor> +
+

Show the given document in a text editor. A column can be provided +to control where the editor is being shown. Might change the active editor.

+
+
+ + + + + + + +
ParameterDescription
document: TextDocument

A text document to be shown.

+
column?: ViewColumn

A view column in which the editor should be shown. The default is the active, other values +are adjusted to be Min(column, columnCount + 1), the active-column is not adjusted. Use ViewColumn.Beside +to open the editor to the side of the currently active one.

+
preserveFocus?: boolean

When true the editor will not take focus.

+
ReturnsDescription
Thenable<TextEditor>

A promise that resolves to an editor.

+
+
+
+ + + +showTextDocument(document: TextDocument, options?: TextDocumentShowOptions): Thenable<TextEditor> +
+

Show the given document in a text editor. Options can be provided +to control options of the editor is being shown. Might change the active editor.

+
+
+ + + + + + +
ParameterDescription
document: TextDocument

A text document to be shown.

+
options?: TextDocumentShowOptions

(#TextDocumentShowOptions) to configure the behavior of showing the editor.

+
ReturnsDescription
Thenable<TextEditor>

A promise that resolves to an editor.

+
+
+
+ + + +showTextDocument(uri: Uri, options?: TextDocumentShowOptions): Thenable<TextEditor> +
+

A short-hand for openTextDocument(uri).then(document => showTextDocument(document, options)).

+ +
+
+ + + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
options?: TextDocumentShowOptions

(#TextDocumentShowOptions) to configure the behavior of showing the editor.

+
ReturnsDescription
Thenable<TextEditor>

A promise that resolves to an editor.

+
+
+
+ + + +showWarningMessage(message: string, ...items: string[]): Thenable<string | undefined> +
+

Show a warning message.

+ +
+
+ + + + + + +
ParameterDescription
message: string

The message to show.

+
...items: string[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showWarningMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined> +
+

Show a warning message.

+ +
+
+ + + + + + + +
ParameterDescription
message: string

The message to show.

+
options: MessageOptions

Configures the behaviour of the message.

+
...items: string[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showWarningMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined> +
+

Show a warning message.

+ +
+
+ + + + + + +
ParameterDescription
message: string

The message to show.

+
...items: T[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showWarningMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined> +
+

Show a warning message.

+ +
+
+ + + + + + + +
ParameterDescription
message: string

The message to show.

+
options: MessageOptions

Configures the behaviour of the message.

+
...items: T[]

A set of items that will be rendered as actions in the message.

+
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

+
+
+
+ + + +showWorkspaceFolderPick(options?: WorkspaceFolderPickOptions): Thenable<WorkspaceFolder | undefined> +
+

Shows a selection list of workspace folders to pick from. +Returns undefined if no folder is open.

+
+
+ + + + + +
ParameterDescription
options?: WorkspaceFolderPickOptions

Configures the behavior of the workspace folder list.

+
ReturnsDescription
Thenable<WorkspaceFolder | undefined>

A promise that resolves to the workspace folder or undefined.

+
+
+
+ + + +withProgress<R>(options: ProgressOptions, task: (progress: Progress<{increment: number, message: string}>, token: CancellationToken) => Thenable<R>): Thenable<R> +
+

Show progress in the editor. Progress is shown while running the given callback +and while the promise it returned isn't resolved nor rejected. The location at which +progress should show (and other details) is defined via the passed ProgressOptions.

+
+
+ + + + + + +
ParameterDescription
options: ProgressOptions
task: (progress: Progress<{increment: number, message: string}>, token: CancellationToken) => Thenable<R>

A callback returning a promise. Progress state can be reported with +the provided progress-object.

+

To report discrete progress, use increment to indicate how much work has been completed. Each call with +a increment value will be summed up and reflected as overall progress until 100% is reached (a value of +e.g. 10 accounts for 10% of work done). +Note that currently only ProgressLocation.Notification is capable of showing discrete progress.

+

To monitor if the operation has been cancelled by the user, use the provided CancellationToken. +Note that currently only ProgressLocation.Notification is supporting to show a cancel button to cancel the +long running operation.

+
ReturnsDescription
Thenable<R>

The thenable the task-callback returned.

+
+
+
+ + + +withScmProgress<R>(task: (progress: Progress<number>) => Thenable<R>): Thenable<R> +
+

Show progress in the Source Control viewlet while running the given callback and while +its returned promise isn't resolve or rejected.

+
    +
  • deprecated - Use withProgress instead.
    • +
+
+
+ + + + + +
ParameterDescription
task: (progress: Progress<number>) => Thenable<R>

A callback returning a promise. Progress increments can be reported with +the provided progress-object.

+
ReturnsDescription
Thenable<R>

The thenable the task did return.

+
+
+
+ +## workspace + + + +

Namespace for dealing with the current workspace. A workspace is the representation +of the folder that has been opened. There is no workspace when just a file but not a +folder has been opened.

+

The workspace offers support for listening to fs +events and for finding files. Both perform well and run outside +the editor-process so that they should be always used instead of nodejs-equivalents.

+
+ +#### Variables + + + +name: string | undefined +
+

The name of the workspace. undefined when no folder +has been opened.

+
    +
  • readonly
    • +
+
+
+ + + +rootPath: string | undefined +
+

The folder that is open in the editor. undefined when no folder +has been opened.

+ +
    +
  • readonly
    • +
+
+
+ + + +textDocuments: TextDocument[] +
+

All text documents currently known to the system.

+
    +
  • readonly
    • +
+
+
+ + + +workspaceFolders: WorkspaceFolder[] | undefined +
+

List of workspace folders or undefined when no folder is open. +Note that the first entry corresponds to the value of rootPath.

+
    +
  • readonly
    • +
+
+
+ +#### Events + + + +onDidChangeConfiguration: Event<ConfigurationChangeEvent> +
+

An event that is emitted when the configuration changed.

+
+
+ + + +onDidChangeTextDocument: Event<TextDocumentChangeEvent> +
+

An event that is emitted when a text document is changed. This usually happens +when the contents changes but also when other things like the +dirty-state changes.

+
+
+ + + +onDidChangeWorkspaceFolders: Event<WorkspaceFoldersChangeEvent> +
+

An event that is emitted when a workspace folder is added or removed.

+
+
+ + + +onDidCloseTextDocument: Event<TextDocument> +
+

An event that is emitted when a text document is disposed or when the language id +of a text document has been changed.

+

To add an event listener when a visible text document is closed, use the TextEditor events in the +window namespace. Note that this event is not emitted when a TextEditor is closed +but the document remains open in another visible text editor.

+
+
+ + + +onDidOpenTextDocument: Event<TextDocument> +
+

An event that is emitted when a text document is opened or when the language id +of a text document has been changed.

+

To add an event listener when a visible text document is opened, use the TextEditor events in the +window namespace. Note that:

+ +
+
+ + + +onDidSaveTextDocument: Event<TextDocument> +
+

An event that is emitted when a text document is saved to disk.

+
+
+ + + +onWillSaveTextDocument: Event<TextDocumentWillSaveEvent> +
+

An event that is emitted when a text document will be saved to disk.

+

Note 1: Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor +might save without firing this event. For instance when shutting down with dirty files.

+

Note 2: Subscribers are called sequentially and they can delay saving +by registering asynchronous work. Protection against misbehaving listeners is implemented as such:

+
    +
  • there is an overall time budget that all listeners share and if that is exhausted no further listener is called
    • +
  • listeners that take a long time or produce errors frequently will not be called anymore
    • +
+

The current thresholds are 1.5 seconds as overall time budget and a listener can misbehave 3 times before being ignored.

+
+
+ +#### Functions + + + +applyEdit(edit: WorkspaceEdit): Thenable<boolean> +
+

Make changes to one or many resources or create, delete, and rename resources as defined by the given +workspace edit.

+

All changes of a workspace edit are applied in the same order in which they have been added. If +multiple textual inserts are made at the same position, these strings appear in the resulting text +in the order the 'inserts' were made. Invalid sequences like 'delete file a' -> 'insert text in file a' +cause failure of the operation.

+

When applying a workspace edit that consists only of text edits an 'all-or-nothing'-strategy is used. +A workspace edit with resource creations or deletions aborts the operation, e.g. consective edits will +not be attempted, when a single edit fails.

+
+
+ + + + + +
ParameterDescription
edit: WorkspaceEdit

A workspace edit.

+
ReturnsDescription
Thenable<boolean>

A thenable that resolves when the edit could be applied.

+
+
+
+ + + +asRelativePath(pathOrUri: string | Uri, includeWorkspaceFolder?: boolean): string +
+

Returns a path that is relative to the workspace folder or folders.

+

When there are no workspace folders or when the path +is not contained in them, the input is returned.

+
+
+ + + + + + +
ParameterDescription
pathOrUri: string | Uri

A path or uri. When a uri is given its fsPath is used.

+
includeWorkspaceFolder?: boolean

When true and when the given path is contained inside a +workspace folder the name of the workspace is prepended. Defaults to true when there are +multiple workspace folders and false otherwise.

+
ReturnsDescription
string

A path relative to the root or the input.

+
+
+
+ + + +createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher +
+

Creates a file system watcher.

+

A glob pattern that filters the file events on their absolute path must be provided. Optionally, +flags to ignore certain kinds of events can be provided. To stop listening to events the watcher must be disposed.

+

Note that only files within the current workspace folders can be watched.

+
+
+ + + + + + + + +
ParameterDescription
globPattern: GlobPattern

A glob pattern that is applied to the absolute paths of created, changed, +and deleted files. Use a relative pattern to limit events to a certain workspace folder.

+
ignoreCreateEvents?: boolean

Ignore when files have been created.

+
ignoreChangeEvents?: boolean

Ignore when files have been changed.

+
ignoreDeleteEvents?: boolean

Ignore when files have been deleted.

+
ReturnsDescription
FileSystemWatcher

A new file system watcher instance.

+
+
+
+ + + +findFiles(include: GlobPattern, exclude?: GlobPattern | null, maxResults?: number, token?: CancellationToken): Thenable<Uri[]> +
+

Find files across all workspace folders in the workspace.

+
    +
  • sample - findFiles('**/*.js', '**/node_modules/**', 10)
    • +
+
+
+ + + + + + + + +
ParameterDescription
include: GlobPattern

A glob pattern that defines the files to search for. The glob pattern +will be matched against the file paths of resulting matches relative to their workspace. Use a relative pattern +to restrict the search results to a workspace folder.

+
exclude?: GlobPattern | null

A glob pattern that defines files and folders to exclude. The glob pattern +will be matched against the file paths of resulting matches relative to their workspace. When undefined only default excludes will +apply, when null no excludes will apply.

+
maxResults?: number

An upper-bound for the result.

+
token?: CancellationToken

A token that can be used to signal cancellation to the underlying search engine.

+
ReturnsDescription
Thenable<Uri[]>

A thenable that resolves to an array of resource identifiers. Will return no results if no +workspace folders are opened.

+
+
+
+ + + +getConfiguration(section?: string, resource?: Uri | null): WorkspaceConfiguration +
+

Get a workspace configuration object.

+

When a section-identifier is provided only that part of the configuration +is returned. Dots in the section-identifier are interpreted as child-access, +like { myExt: { setting: { doIt: true }}} and getConfiguration('myExt.setting').get('doIt') === true.

+

When a resource is provided, configuration scoped to that resource is returned.

+
+
+ + + + + + +
ParameterDescription
section?: string

A dot-separated identifier.

+
resource?: Uri | null

A resource for which the configuration is asked for

+
ReturnsDescription
WorkspaceConfiguration

The full configuration or a subset.

+
+
+
+ + + +getWorkspaceFolder(uri: Uri): WorkspaceFolder | undefined +
+

Returns the workspace folder that contains a given uri.

+
    +
  • returns undefined when the given uri doesn't match any workspace folder
    • +
  • returns the input when the given uri is a workspace folder itself
    • +
+
+
+ + + + + +
ParameterDescription
uri: Uri

An uri.

+
ReturnsDescription
WorkspaceFolder | undefined

A workspace folder or undefined

+
+
+
+ + + +openTextDocument(uri: Uri): Thenable<TextDocument> +
+

Opens a document. Will return early if this document is already open. Otherwise +the document is loaded and the didOpen-event fires.

+

The document is denoted by an uri. Depending on the scheme the +following rules apply:

+
    +
  • file-scheme: Open a file on disk, will be rejected if the file does not exist or cannot be loaded.
    • +
  • untitled-scheme: A new file that should be saved on disk, e.g. untitled:c:\frodo\new.js. The language +will be derived from the file name.
    • +
  • For all other schemes the registered text document content providers are consulted.
    • +
+

Note that the lifecycle of the returned document is owned by the editor and not by the extension. That means an +onDidClose-event can occur at any time after opening it.

+
+
+ + + + + +
ParameterDescription
uri: Uri

Identifies the resource to open.

+
ReturnsDescription
Thenable<TextDocument>

A promise that resolves to a document.

+
+
+
+ + + +openTextDocument(fileName: string): Thenable<TextDocument> +
+

A short-hand for openTextDocument(Uri.file(fileName)).

+ +
+
+ + + + + +
ParameterDescription
fileName: string

A name of a file on disk.

+
ReturnsDescription
Thenable<TextDocument>

A promise that resolves to a document.

+
+
+
+ + + +openTextDocument(options?: {content: string, language: string}): Thenable<TextDocument> +
+

Opens an untitled text document. The editor will prompt the user for a file +path when the document is to be saved. The options parameter allows to +specify the language and/or the content of the document.

+
+
+ + + + + +
ParameterDescription
options?: {content: string, language: string}

Options to control how the document will be created.

+
ReturnsDescription
Thenable<TextDocument>

A promise that resolves to a document.

+
+
+
+ + + +registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options?: {isCaseSensitive: boolean, isReadonly: boolean}): Disposable +
+

Register a filesystem provider for a given scheme, e.g. ftp.

+

There can only be one provider per scheme and an error is being thrown when a scheme +has been claimed by another provider or when it is reserved.

+
+
+ + + + + + + +
ParameterDescription
scheme: string

The uri-scheme the provider registers for.

+
provider: FileSystemProvider

The filesystem provider.

+
options?: {isCaseSensitive: boolean, isReadonly: boolean}

Immutable metadata about the provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerTaskProvider(type: string, provider: TaskProvider): Disposable +
+

Register a task provider.

+
    +
  • deprecated - Use the corresponding function on the tasks namespace instead
    • +
+
+
+ + + + + + +
ParameterDescription
type: string

The task kind type this provider is registered for.

+
provider: TaskProvider

A task provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +registerTextDocumentContentProvider(scheme: string, provider: TextDocumentContentProvider): Disposable +
+

Register a text document content provider.

+

Only one provider can be registered per scheme.

+
+
+ + + + + + +
ParameterDescription
scheme: string

The uri-scheme to register for.

+
provider: TextDocumentContentProvider

A content provider.

+
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

+
+
+
+ + + +saveAll(includeUntitled?: boolean): Thenable<boolean> +
+

Save all dirty files.

+
+
+ + + + + +
ParameterDescription
includeUntitled?: boolean

Also save files that have been created during this session.

+
ReturnsDescription
Thenable<boolean>

A thenable that resolves when the files have been saved.

+
+
+
+ + + +updateWorkspaceFolders(start: number, deleteCount: number | undefined | null, ...workspaceFoldersToAdd: {name: string, uri: Uri}[]): boolean +
+

This method replaces deleteCount workspace folders starting at index start +by an optional set of workspaceFoldersToAdd on the vscode.workspace.workspaceFolders array. This "splice" +behavior can be used to add, remove and change workspace folders in a single operation.

+

If the first workspace folder is added, removed or changed, the currently executing extensions (including the +one that called this method) will be terminated and restarted so that the (deprecated) rootPath property is +updated to point to the first workspace folder.

+

Use the onDidChangeWorkspaceFolders() event to get notified when the +workspace folders have been updated.

+

Example: adding a new workspace folder at the end of workspace folders

+ +
workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, { uri: ...});
+
+

Example: removing the first workspace folder

+ +
workspace.updateWorkspaceFolders(0, 1);
+
+

Example: replacing an existing workspace folder with a new one

+ +
workspace.updateWorkspaceFolders(0, 1, { uri: ...});
+
+

It is valid to remove an existing workspace folder and add it again with a different name +to rename that folder.

+

Note: it is not valid to call updateWorkspaceFolders() multiple times +without waiting for the onDidChangeWorkspaceFolders() to fire.

+
+
+ + + + + + + +
ParameterDescription
start: number

the zero-based location in the list of currently opened workspace folders +from which to start deleting workspace folders.

+
deleteCount: number | undefined | null

the optional number of workspace folders to remove.

+
...workspaceFoldersToAdd: {name: string, uri: Uri}[]

the optional variable set of workspace folders to add in place of the deleted ones. +Each workspace is identified with a mandatory URI and an optional name.

+
ReturnsDescription
boolean

true if the operation was successfully started and false otherwise if arguments were used that would result +in invalid workspace folder state (e.g. 2 folders with the same URI).

+
+
+
+ +### Breakpoint + + + +

The base class of all breakpoint types.

+
+ +#### Constructors + + + +new Breakpoint(enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): Breakpoint +
+
+
+ + + + + + + + +
ParameterDescription
enabled?: boolean
condition?: string
hitCondition?: string
logMessage?: string
ReturnsDescription
Breakpoint
+
+
+ +#### Properties + + + +condition?: string +
+

An optional expression for conditional breakpoints.

+
+
+ + + +enabled: boolean +
+

Is breakpoint enabled.

+
+
+ + + +hitCondition?: string +
+

An optional expression that controls how many hits of the breakpoint are ignored.

+
+
+ + + +id: string +
+

The unique ID of the breakpoint.

+
+
+ + + +logMessage?: string +
+

An optional message that gets logged when this breakpoint is hit. Embedded expressions within {} are interpolated by the debug adapter.

+
+
+ +### BreakpointsChangeEvent + + + +

An event describing the changes to the set of breakpoints.

+
+ +#### Properties + + + +added: Breakpoint[] +
+

Added breakpoints.

+
+
+ + + +changed: Breakpoint[] +
+

Changed breakpoints.

+
+
+ + + +removed: Breakpoint[] +
+

Removed breakpoints.

+
+
+ +### CancellationToken + + + +

A cancellation token is passed to an asynchronous or long running +operation to request cancellation, like cancelling a request +for completion items because the user continued to type.

+

To get an instance of a CancellationToken use a +CancellationTokenSource.

+
+ +#### Properties + + + +isCancellationRequested: boolean +
+

Is true when the token has been cancelled, false otherwise.

+
+
+ + + +onCancellationRequested: Event<any> +
+

An event which fires upon cancellation.

+
+
+ +### CancellationTokenSource + + + +

A cancellation source creates and controls a cancellation token.

+
+ +#### Properties + + + +token: CancellationToken +
+

The cancellation token of this source.

+
+
+ +#### Methods + + + +cancel(): void +
+

Signal cancellation on the token.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +dispose(): void +
+

Dispose object and free resources.

+
+
+ + + +
ReturnsDescription
void
+
+
+ +### CharacterPair + + + +

A tuple of two characters, like a pair of +opening and closing brackets.

+
+ + + +CharacterPair: [string, string] + +### Clipboard + + + +

The clipboard provides read and write access to the system's clipboard.

+
+ +#### Methods + + + +readText(): Thenable<string> +
+

Read the current clipboard contents as text.

+
+
+ + + +
ReturnsDescription
Thenable<string>

A thenable that resolves to a string.

+
+
+
+ + + +writeText(value: string): Thenable<void> +
+

Writes text into the clipboard.

+
+
+ + + + + +
ParameterDescription
value: string
ReturnsDescription
Thenable<void>

A thenable that resolves when writing happened.

+
+
+
+ +### CodeAction + + + +

A code action represents a change that can be performed in code, e.g. to fix a problem or +to refactor code.

+

A CodeAction must set either edit and/or a command. If both are supplied, the edit is applied first, then the command is executed.

+
+ +#### Constructors + + + +new CodeAction(title: string, kind?: CodeActionKind): CodeAction +
+

Creates a new code action.

+

A code action must have at least a title and edits +and/or a command.

+
+
+ + + + + + +
ParameterDescription
title: string

The title of the code action.

+
kind?: CodeActionKind

The kind of the code action.

+
ReturnsDescription
CodeAction
+
+
+ +#### Properties + + + +command?: Command +
+

A command this code action executes.

+
+
+ + + +diagnostics?: Diagnostic[] +
+

Diagnostics that this code action resolves.

+
+
+ + + +edit?: WorkspaceEdit +
+

A workspace edit this code action performs.

+
+
+ + + +kind?: CodeActionKind +
+

Kind of the code action.

+

Used to filter code actions.

+
+
+ + + +title: string +
+

A short, human-readable, title for this code action.

+
+
+ +### CodeActionContext + + + +

Contains additional diagnostic information about the context in which +a code action is run.

+
+ +#### Events + + + +only?: CodeActionKind +
+

Requested kind of actions to return.

+

Actions not of this kind are filtered out before being shown by the lightbulb.

+
+
+ +#### Properties + + + +diagnostics: Diagnostic[] +
+

An array of diagnostics.

+
+
+ +### CodeActionKind + + + +

Kind of a code action.

+

Kinds are a hierarchical list of identifiers separated by ., e.g. "refactor.extract.function".

+

Code action kinds are used by VS Code for UI elements such as the refactoring context menu. Users +can also trigger code actions with a specific kind with the editor.action.codeAction command.

+
+ +#### Static + + + +Empty: CodeActionKind +
+

Empty kind.

+
+
+ + + +QuickFix: CodeActionKind +
+

Base kind for quickfix actions: quickfix.

+

Quick fix actions address a problem in the code and are shown in the normal code action context menu.

+
+
+ + + +Refactor: CodeActionKind +
+

Base kind for refactoring actions: refactor

+

Refactoring actions are shown in the refactoring context menu.

+
+
+ + + +RefactorExtract: CodeActionKind +
+

Base kind for refactoring extraction actions: refactor.extract

+

Example extract actions:

+
    +
  • Extract method
    • +
  • Extract function
    • +
  • Extract variable
    • +
  • Extract interface from class
    • +
  • ...
    • +
+
+
+ + + +RefactorInline: CodeActionKind +
+

Base kind for refactoring inline actions: refactor.inline

+

Example inline actions:

+
    +
  • Inline function
    • +
  • Inline variable
    • +
  • Inline constant
    • +
  • ...
    • +
+
+
+ + + +RefactorRewrite: CodeActionKind +
+

Base kind for refactoring rewrite actions: refactor.rewrite

+

Example rewrite actions:

+
    +
  • Convert JavaScript function to class
    • +
  • Add or remove parameter
    • +
  • Encapsulate field
    • +
  • Make method static
    • +
  • Move method to base class
    • +
  • ...
    • +
+
+
+ + + +Source: CodeActionKind +
+

Base kind for source actions: source

+

Source code actions apply to the entire file and can be run on save +using editor.codeActionsOnSave. They also are shown in source context menu.

+
+
+ + + +SourceOrganizeImports: CodeActionKind +
+

Base kind for an organize imports source action: source.organizeImports.

+
+
+ +#### Constructors + + + +new CodeActionKind(value: string): CodeActionKind +
+
+
+ + + + + +
ParameterDescription
value: string
ReturnsDescription
CodeActionKind
+
+
+ +#### Properties + + + +value?: string +
+

String value of the kind, e.g. "refactor.extract.function".

+
+
+ +#### Methods + + + +append(parts: string): CodeActionKind +
+

Create a new kind by appending a more specific selector to the current kind.

+

Does not modify the current kind.

+
+
+ + + + + +
ParameterDescription
parts: string
ReturnsDescription
CodeActionKind
+
+
+ + + +contains(other: CodeActionKind): boolean +
+

Does this kind contain other?

+

The kind "refactor" for example contains "refactor.extract" and `"refactor.extract.function", but not "unicorn.refactor.extract" or "refactory.extract"

+
+
+ + + + + +
ParameterDescription
other: CodeActionKind

Kind to check.

+
ReturnsDescription
boolean
+
+
+ +### CodeActionProvider + + + +

The code action interface defines the contract between extensions and +the light bulb feature.

+

A code action can be any command that is known to the system.

+
+ +#### Methods + + + +provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken): ProviderResult<Command | CodeAction[]> +
+

Provide commands for the given document and range.

+
+
+ + + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
range: Range | Selection

The selector or range for which the command was invoked. This will always be a selection if +there is a currently active editor.

+
context: CodeActionContext

Context carrying additional information.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Command | CodeAction[]>

An array of commands, quick fixes, or refactorings or a thenable of such. The lack of a result can be +signaled by returning undefined, null, or an empty array.

+
+
+
+ +### CodeActionProviderMetadata + + + +

Metadata about the type of code actions that a CodeActionProvider providers

+
+ +#### Properties + + + +providedCodeActionKinds?: ReadonlyArray<CodeActionKind> +
+

CodeActionKinds that this provider may return.

+

The list of kinds may be generic, such as CodeActionKind.Refactor, or the provider +may list our every specific kind they provide, such as CodeActionKind.Refactor.Extract.append('function)`

+
+
+ +### CodeLens + + + +

A code lens represents a command that should be shown along with +source text, like the number of references, a way to run tests, etc.

+

A code lens is unresolved when no command is associated to it. For performance +reasons the creation of a code lens and resolving should be done to two stages.

+ + +
+ +#### Constructors + + + +new CodeLens(range: Range, command?: Command): CodeLens +
+

Creates a new code lens object.

+
+
+ + + + + + +
ParameterDescription
range: Range

The range to which this code lens applies.

+
command?: Command

The command associated to this code lens.

+
ReturnsDescription
CodeLens
+
+
+ +#### Properties + + + +command?: Command +
+

The command this code lens represents.

+
+
+ + + +isResolved: boolean +
+

true when there is a command associated.

+
+
+ + + +range: Range +
+

The range in which this code lens is valid. Should only span a single line.

+
+
+ +### CodeLensProvider + + + +

A code lens provider adds commands to source text. The commands will be shown +as dedicated horizontal lines in between the source text.

+
+ +#### Events + + + +onDidChangeCodeLenses?: Event<void> +
+

An optional event to signal that the code lenses from this provider have changed.

+
+
+ +#### Methods + + + +provideCodeLenses(document: TextDocument, token: CancellationToken): ProviderResult<CodeLens[]> +
+

Compute a list of lenses. This call should return as fast as possible and if +computing the commands is expensive implementors should only return code lens objects with the +range set and implement resolve.

+
+
+ + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<CodeLens[]>

An array of code lenses or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined, null, or an empty array.

+
+
+
+ + + +resolveCodeLens(codeLens: CodeLens, token: CancellationToken): ProviderResult<CodeLens> +
+

This function will be called for each visible code lens, usually when scrolling and after +calls to compute-lenses.

+
+
+ + + + + + +
ParameterDescription
codeLens: CodeLens

code lens that must be resolved.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<CodeLens>

The given, resolved code lens or thenable that resolves to such.

+
+
+
+ +### Color + + + +

Represents a color in RGBA space.

+
+ +#### Constructors + + + +new Color(red: number, green: number, blue: number, alpha: number): Color +
+

Creates a new color instance.

+
+
+ + + + + + + + +
ParameterDescription
red: number

The red component.

+
green: number

The green component.

+
blue: number

The blue component.

+
alpha: number

The alpha component.

+
ReturnsDescription
Color
+
+
+ +#### Properties + + + +alpha: number +
+

The alpha component of this color in the range [0-1].

+
+
+ + + +blue: number +
+

The blue component of this color in the range [0-1].

+
+
+ + + +green: number +
+

The green component of this color in the range [0-1].

+
+
+ + + +red: number +
+

The red component of this color in the range [0-1].

+
+
+ +### ColorInformation + + + +

Represents a color range from a document.

+
+ +#### Constructors + + + +new ColorInformation(range: Range, color: Color): ColorInformation +
+

Creates a new color range.

+
+
+ + + + + + +
ParameterDescription
range: Range

The range the color appears in. Must not be empty.

+
color: Color

The value of the color.

+
ReturnsDescription
ColorInformation
+
+
+ +#### Properties + + + +color: Color +
+

The actual color value for this color range.

+
+
+ + + +range: Range +
+

The range in the document where this color appears.

+
+
+ +### ColorPresentation + + + +

A color presentation object describes how a color should be represented as text and what +edits are required to refer to it from source code.

+

For some languages one color can have multiple presentations, e.g. css can represent the color red with +the constant Red, the hex-value #ff0000, or in rgba and hsla forms. In csharp other representations +apply, e.g System.Drawing.Color.Red.

+
+ +#### Constructors + + + +new ColorPresentation(label: string): ColorPresentation +
+

Creates a new color presentation.

+
+
+ + + + + +
ParameterDescription
label: string

The label of this color presentation.

+
ReturnsDescription
ColorPresentation
+
+
+ +#### Properties + + + +additionalTextEdits?: TextEdit[] +
+

An optional array of additional text edits that are applied when +selecting this color presentation. Edits must not overlap with the main edit nor with themselves.

+
+
+ + + +label: string +
+

The label of this color presentation. It will be shown on the color +picker header. By default this is also the text that is inserted when selecting +this color presentation.

+
+
+ + + +textEdit?: TextEdit +
+

An edit which is applied to a document when selecting +this presentation for the color. When falsy the label +is used.

+
+
+ +### Command + + + +

Represents a reference to a command. Provides a title which +will be used to represent a command in the UI and, optionally, +an array of arguments which will be passed to the command handler +function when invoked.

+
+ +#### Properties + + + +arguments?: any[] +
+

Arguments that the command handler should be +invoked with.

+
+
+ + + +command: string +
+

The identifier of the actual command handler.

+ +
+
+ + + +title: string +
+

Title of the command, like save.

+
+
+ + + +tooltip?: string +
+

A tooltip for the command, when represented in the UI.

+
+
+ +### CommentRule + + + +

Describes how comments for a language work.

+
+ +#### Properties + + + +blockComment?: CharacterPair +
+

The block comment character pair, like /* block comment *&#47;

+
+
+ + + +lineComment?: string +
+

The line comment token, like // this is a comment

+
+
+ +### CompletionContext + + + +

Contains additional information about the context in which +completion provider is triggered.

+
+ +#### Properties + + + +triggerCharacter?: string +
+

Character that triggered the completion item provider.

+

undefined if provider was not triggered by a character.

+

The trigger character is already in the document when the completion provider is triggered.

+
+
+ + + +triggerKind: CompletionTriggerKind +
+

How the completion was triggered.

+
+
+ +### CompletionItem + + + +

A completion item represents a text snippet that is proposed to complete text that is being typed.

+

It is sufficient to create a completion item from just a label. In that +case the completion item will replace the word +until the cursor with the given label or insertText. Otherwise the +given edit is used.

+

When selecting a completion item in the editor its defined or synthesized text edit will be applied +to all cursors/selections whereas additionalTextEdits will be +applied as provided.

+ + +
+ +#### Constructors + + + +new CompletionItem(label: string, kind?: CompletionItemKind): CompletionItem +
+

Creates a new completion item.

+

Completion items must have at least a label which then +will be used as insert text as well as for sorting and filtering.

+
+
+ + + + + + +
ParameterDescription
label: string

The label of the completion.

+
kind?: CompletionItemKind

The kind of the completion.

+
ReturnsDescription
CompletionItem
+
+
+ +#### Properties + + + +additionalTextEdits?: TextEdit[] +
+

An optional array of additional text edits that are applied when +selecting this completion. Edits must not overlap with the main edit +nor with themselves.

+
+
+ + + +command?: Command +
+

An optional command that is executed after inserting this completion. Note that +additional modifications to the current document should be described with the +additionalTextEdits-property.

+
+
+ + + +commitCharacters?: string[] +
+

An optional set of characters that when pressed while this completion is active will accept it first and +then type that character. Note that all commit characters should have length=1 and that superfluous +characters will be ignored.

+
+
+ + + +detail?: string +
+

A human-readable string with additional information +about this item, like type or symbol information.

+
+
+ + + +documentation?: string | MarkdownString +
+

A human-readable string that represents a doc-comment.

+
+
+ + + +filterText?: string +
+

A string that should be used when filtering a set of +completion items. When falsy the label +is used.

+
+
+ + + +insertText?: string | SnippetString +
+

A string or snippet that should be inserted in a document when selecting +this completion. When falsy the label +is used.

+
+
+ + + +keepWhitespace?: boolean +
+

Keep whitespace of the insertText as is. By default, the editor adjusts leading +whitespace of new lines so that they match the indentation of the line for which the item is accepeted - setting +this to true will prevent that.

+
+
+ + + +kind?: CompletionItemKind +
+

The kind of this completion item. Based on the kind +an icon is chosen by the editor.

+
+
+ + + +label: string +
+

The label of this completion item. By default +this is also the text that is inserted when selecting +this completion.

+
+
+ + + +preselect?: boolean +
+

Select this item when showing. Note that only one completion item can be selected and +that the editor decides which item that is. The rule is that the first item of those +that match best is selected.

+
+
+ + + +range?: Range +
+

A range of text that should be replaced by this completion item.

+

Defaults to a range from the start of the current word to the +current position.

+

Note: The range must be a single line and it must +contain the position at which completion has been requested.

+
+
+ + + +sortText?: string +
+

A string that should be used when comparing this item +with other items. When falsy the label +is used.

+
+
+ + + +textEdit?: TextEdit +
+
    +
  • deprecated - Use CompletionItem.insertText and CompletionItem.range instead.
    • +
+

An edit which is applied to a document when selecting +this completion. When an edit is provided the value of +insertText is ignored.

+

The range of the edit must be single-line and on the same +line completions were requested at.

+
+
+ +### CompletionItemKind + + + +

Completion item kinds.

+
+ +#### Enumeration members + + + +Class +
+6 +
+ + + +Color +
+15 +
+ + + +Constant +
+20 +
+ + + +Constructor +
+3 +
+ + + +Enum +
+12 +
+ + + +EnumMember +
+19 +
+ + + +Event +
+22 +
+ + + +Field +
+4 +
+ + + +File +
+16 +
+ + + +Folder +
+18 +
+ + + +Function +
+2 +
+ + + +Interface +
+7 +
+ + + +Keyword +
+13 +
+ + + +Method +
+1 +
+ + + +Module +
+8 +
+ + + +Operator +
+23 +
+ + + +Property +
+9 +
+ + + +Reference +
+17 +
+ + + +Snippet +
+14 +
+ + + +Struct +
+21 +
+ + + +Text +
+0 +
+ + + +TypeParameter +
+24 +
+ + + +Unit +
+10 +
+ + + +Value +
+11 +
+ + + +Variable +
+5 +
+ +### CompletionItemProvider + + + +

The completion item provider interface defines the contract between extensions and +IntelliSense.

+

Providers can delay the computation of the detail +and documentation properties by implementing the +resolveCompletionItem-function. However, properties that +are needed for the initial sorting and filtering, like sortText, filterText, insertText, and range, must +not be changed during resolve.

+

Providers are asked for completions either explicitly by a user gesture or -depending on the configuration- +implicitly when typing words or trigger characters.

+
+ +#### Methods + + + +provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken, context: CompletionContext): ProviderResult<CompletionItem[] | CompletionList> +
+

Provide completion items for the given position and document.

+
+
+ + + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
context: CompletionContext

How the completion was triggered.

+
ReturnsDescription
ProviderResult<CompletionItem[] | CompletionList>

An array of completions, a completion list, or a thenable that resolves to either. +The lack of a result can be signaled by returning undefined, null, or an empty array.

+
+
+
+ + + +resolveCompletionItem(item: CompletionItem, token: CancellationToken): ProviderResult<CompletionItem> +
+

Given a completion item fill in more data, like doc-comment +or details.

+

The editor will only resolve a completion item once.

+
+
+ + + + + + +
ParameterDescription
item: CompletionItem

A completion item currently active in the UI.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<CompletionItem>

The resolved completion item or a thenable that resolves to of such. It is OK to return the given +item. When no result is returned, the given item will be used.

+
+
+
+ +### CompletionList + + + +

Represents a collection of completion items to be presented +in the editor.

+
+ +#### Constructors + + + +new CompletionList(items?: CompletionItem[], isIncomplete?: boolean): CompletionList +
+

Creates a new completion list.

+
+
+ + + + + + +
ParameterDescription
items?: CompletionItem[]

The completion items.

+
isIncomplete?: boolean

The list is not complete.

+
ReturnsDescription
CompletionList
+
+
+ +#### Properties + + + +isIncomplete?: boolean +
+

This list is not complete. Further typing should result in recomputing +this list.

+
+
+ + + +items: CompletionItem[] +
+

The completion items.

+
+
+ +### CompletionTriggerKind + + + +

How a completion provider was triggered

+
+ +#### Enumeration members + + + +Invoke +
+0 +
+ + + +TriggerCharacter +
+1 +
+ + + +TriggerForIncompleteCompletions +
+2 +
+ +### ConfigurationChangeEvent + + + +

An event describing the change in Configuration

+
+ +#### Methods + + + +affectsConfiguration(section: string, resource?: Uri): boolean +
+

Returns true if the given section for the given resource (if provided) is affected.

+
+
+ + + + + + +
ParameterDescription
section: string

Configuration name, supports dotted names.

+
resource?: Uri

A resource Uri.

+
ReturnsDescription
boolean

true if the given section for the given resource (if provided) is affected.

+
+
+
+ +### ConfigurationTarget + + + +

The configuration target

+
+ +#### Enumeration members + + + +Global +
+1 +
+ + + +Workspace +
+2 +
+ + + +WorkspaceFolder +
+3 +
+ +### DebugAdapterDescriptor + + + +
+ + + +DebugAdapterDescriptor: DebugAdapterExecutable | DebugAdapterServer + +### DebugAdapterDescriptorFactory + + + +
+ +#### Methods + + + +createDebugAdapterDescriptor(session: DebugSession, executable: DebugAdapterExecutable | undefined): ProviderResult<DebugAdapterDescriptor> +
+

'createDebugAdapterDescriptor' is called at the start of a debug session to provide details about the debug adapter to use. +These details must be returned as objects of type DebugAdapterDescriptor. +Currently two types of debug adapters are supported:

+
    +
  • a debug adapter executable is specified as a command path and arguments (see DebugAdapterExecutable),
    • +
  • a debug adapter server reachable via a communication port (see DebugAdapterServer). +If the method is not implemented the default behavior is this: +createDebugAdapter(session: DebugSession, executable: DebugAdapterExecutable) { + if (typeof session.configuration.debugServer === 'number') { +
      return new DebugAdapterServer(session.configuration.debugServer);
+
    } + return executable; +}
    • +
+
+
+ + + + + + +
ParameterDescription
session: DebugSession

The debug session for which the debug adapter will be used.

+
executable: DebugAdapterExecutable | undefined

The debug adapter's executable information as specified in the package.json (or undefined if no such information exists).

+
ReturnsDescription
ProviderResult<DebugAdapterDescriptor>

a debug adapter descriptor or undefined.

+
+
+
+ +### DebugAdapterExecutable + + + +

Represents a debug adapter executable and optional arguments and runtime options passed to it.

+
+ +#### Constructors + + + +new DebugAdapterExecutable(command: string, args?: string[], options?: DebugAdapterExecutableOptions): DebugAdapterExecutable +
+

Creates a description for a debug adapter based on an executable program.

+
+
+ + + + + + + +
ParameterDescription
command: string

The command or executable path that implements the debug adapter.

+
args?: string[]

Optional arguments to be passed to the command or executable.

+
options?: DebugAdapterExecutableOptions

Optional options to be used when starting the command or executable.

+
ReturnsDescription
DebugAdapterExecutable
+
+
+ +#### Properties + + + +args: string[] +
+

The arguments passed to the debug adapter executable. Defaults to an empty array.

+
+
+ + + +command: string +
+

The command or path of the debug adapter executable. +A command must be either an absolute path of an executable or the name of an command to be looked up via the PATH environment variable. +The special value 'node' will be mapped to VS Code's built-in Node.js runtime.

+
+
+ + + +options?: DebugAdapterExecutableOptions +
+

Optional options to be used when the debug adapter is started. +Defaults to undefined.

+
+
+ +### DebugAdapterExecutableOptions + + + +

Options for a debug adapter executable.

+
+ +#### Properties + + + +cwd?: string +
+

The current working directory for the executed debug adapter.

+
+
+ + + +env?: +
+

The additional environment of the executed program or shell. If omitted +the parent process' environment is used. If provided it is merged with +the parent process' environment.

+
+
+ +### DebugAdapterServer + + + +

Represents a debug adapter running as a socket based server.

+
+ +#### Constructors + + + +new DebugAdapterServer(port: number, host?: string): DebugAdapterServer +
+

Create a description for a debug adapter running as a socket based server.

+
+
+ + + + + + +
ParameterDescription
port: number
host?: string
ReturnsDescription
DebugAdapterServer
+
+
+ +#### Properties + + + +host?: string +
+

The host.

+
+
+ + + +port: number +
+

The port.

+
+
+ +### DebugAdapterTracker + + + +

A Debug Adapter Tracker is a means to track the communication between VS Code and a Debug Adapter.

+
+ +#### Events + + + +onDidSendMessage(message: any): void +
+

The debug adapter has sent a Debug Adapter Protocol message to VS Code.

+
+
+ + + + + +
ParameterDescription
message: any
ReturnsDescription
void
+
+
+ + + +onWillReceiveMessage(message: any): void +
+

The debug adapter is about to receive a Debug Adapter Protocol message from VS Code.

+
+
+ + + + + +
ParameterDescription
message: any
ReturnsDescription
void
+
+
+ + + +onWillStartSession(): void +
+

A session with the debug adapter is about to be started.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +onWillStopSession(): void +
+

The debug adapter session is about to be stopped.

+
+
+ + + +
ReturnsDescription
void
+
+
+ +#### Methods + + + +onError(error: Error): void +
+

An error with the debug adapter has occured.

+
+
+ + + + + +
ParameterDescription
error: Error
ReturnsDescription
void
+
+
+ + + +onExit(code: number | undefined, signal: string | undefined): void +
+

The debug adapter has exited with the given exit code or signal.

+
+
+ + + + + + +
ParameterDescription
code: number | undefined
signal: string | undefined
ReturnsDescription
void
+
+
+ +### DebugAdapterTrackerFactory + + + +
+ +#### Methods + + + +createDebugAdapterTracker(session: DebugSession): ProviderResult<DebugAdapterTracker> +
+

The method 'createDebugAdapterTracker' is called at the start of a debug session in order +to return a "tracker" object that provides read-access to the communication between VS Code and a debug adapter.

+
+
+ + + + + +
ParameterDescription
session: DebugSession

The debug session for which the debug adapter tracker will be used.

+
ReturnsDescription
ProviderResult<DebugAdapterTracker>

A debug adapter tracker or undefined.

+
+
+
+ +### DebugConfiguration + + + +

Configuration for a debug session.

+
+ +#### Properties + + + +name: string +
+

The name of the debug session.

+
+
+ + + +request: string +
+

The request type of the debug session.

+
+
+ + + +type: string +
+

The type of the debug session.

+
+
+ +### DebugConfigurationProvider + + + +

A debug configuration provider allows to add the initial debug configurations to a newly created launch.json +and to resolve a launch configuration before it is used to start a new debug session. +A debug configuration provider is registered via #debug.registerDebugConfigurationProvider.

+
+ +#### Methods + + + +provideDebugConfigurations(folder: WorkspaceFolder | undefined, token?: CancellationToken): ProviderResult<DebugConfiguration[]> +
+

Provides initial debug configuration. If more than one debug configuration provider is +registered for the same type, debug configurations are concatenated in arbitrary order.

+
+
+ + + + + + +
ParameterDescription
folder: WorkspaceFolder | undefined

The workspace folder for which the configurations are used or undefined for a folderless setup.

+
token?: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<DebugConfiguration[]>

An array of debug configurations.

+
+
+
+ + + +resolveDebugConfiguration(folder: WorkspaceFolder | undefined, debugConfiguration: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugConfiguration> +
+

Resolves a debug configuration by filling in missing values or by adding/changing/removing attributes. +If more than one debug configuration provider is registered for the same type, the resolveDebugConfiguration calls are chained +in arbitrary order and the initial debug configuration is piped through the chain. +Returning the value 'undefined' prevents the debug session from starting. +Returning the value 'null' prevents the debug session from starting and opens the underlying debug configuration instead.

+
+
+ + + + + + + +
ParameterDescription
folder: WorkspaceFolder | undefined

The workspace folder from which the configuration originates from or undefined for a folderless setup.

+
debugConfiguration: DebugConfiguration

The debug configuration to resolve.

+
token?: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<DebugConfiguration>

The resolved debug configuration or undefined or null.

+
+
+
+ +### DebugConsole + + + +

Represents the debug console.

+
+ +#### Methods + + + +append(value: string): void +
+

Append the given value to the debug console.

+
+
+ + + + + +
ParameterDescription
value: string

A string, falsy values will not be printed.

+
ReturnsDescription
void
+
+
+ + + +appendLine(value: string): void +
+

Append the given value and a line feed character +to the debug console.

+
+
+ + + + + +
ParameterDescription
value: string

A string, falsy values will be printed.

+
ReturnsDescription
void
+
+
+ +### DebugSession + + + +

A debug session.

+
+ +#### Properties + + + +configuration: DebugConfiguration +
+

The "resolved" debug configuration of this session. +"Resolved" means that

+
    +
  • all variables have been substituted and
    • +
  • platform specific attribute sections have been "flattened" for the matching platform and removed for non-matching platforms.
    • +
+
+
+ + + +id: string +
+

The unique ID of this debug session.

+
+
+ + + +name: string +
+

The debug session's name from the debug configuration.

+
+
+ + + +type: string +
+

The debug session's type from the debug configuration.

+
+
+ + + +workspaceFolder: WorkspaceFolder | undefined +
+

The workspace folder of this session or undefined for a folderless setup.

+
+
+ +#### Methods + + + +customRequest(command: string, args?: any): Thenable<any> +
+

Send a custom request to the debug adapter.

+
+
+ + + + + + +
ParameterDescription
command: string
args?: any
ReturnsDescription
Thenable<any>
+
+
+ +### DebugSessionCustomEvent + + + +

A custom Debug Adapter Protocol event received from a debug session.

+
+ +#### Properties + + + +body?: any +
+

Event specific information.

+
+
+ + + +event: string +
+

Type of event.

+
+
+ + + +session: DebugSession +
+

The debug session for which the custom event was received.

+
+
+ +### Declaration + + + +

The declaration of a symbol representation as one or many locations +or [location links][#LocationLink].

+
+ + + +Declaration: Location | Location[] | LocationLink[] + +### DeclarationProvider + + + +

The declaration provider interface defines the contract between extensions and +the go to declaration feature.

+
+ +#### Methods + + + +provideDeclaration(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Declaration> +
+

Provide the declaration of the symbol at the given position and document.

+
+
+ + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Declaration>

A declaration or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined or null.

+
+
+
+ +### DecorationInstanceRenderOptions + + + +
+ +#### Properties + + + +after?: ThemableDecorationAttachmentRenderOptions +
+

Defines the rendering options of the attachment that is inserted after the decorated text.

+
+
+ + + +before?: ThemableDecorationAttachmentRenderOptions +
+

Defines the rendering options of the attachment that is inserted before the decorated text.

+
+
+ + + +dark?: ThemableDecorationInstanceRenderOptions +
+

Overwrite options for dark themes.

+
+
+ + + +light?: ThemableDecorationInstanceRenderOptions +
+

Overwrite options for light themes.

+
+
+ +### DecorationOptions + + + +

Represents options for a specific decoration in a decoration set.

+
+ +#### Properties + + + +hoverMessage?: MarkedString | MarkedString[] +
+

A message that should be rendered when hovering over the decoration.

+
+
+ + + +range: Range +
+

Range to which this decoration is applied. The range must not be empty.

+
+
+ + + +renderOptions?: DecorationInstanceRenderOptions +
+

Render options applied to the current decoration. For performance reasons, keep the +number of decoration specific options small, and use decoration types wherever possible.

+
+
+ +### DecorationRangeBehavior + + + +

Describes the behavior of decorations when typing/editing at their edges.

+
+ +#### Enumeration members + + + +ClosedClosed +
+1 +
+ + + +ClosedOpen +
+3 +
+ + + +OpenClosed +
+2 +
+ + + +OpenOpen +
+0 +
+ +### DecorationRenderOptions + + + +

Represents rendering styles for a text editor decoration.

+
+ +#### Properties + + + +after?: ThemableDecorationAttachmentRenderOptions +
+

Defines the rendering options of the attachment that is inserted after the decorated text.

+
+
+ + + +backgroundColor?: string | ThemeColor +
+

Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations. +Alternatively a color from the color registry can be referenced.

+
+
+ + + +before?: ThemableDecorationAttachmentRenderOptions +
+

Defines the rendering options of the attachment that is inserted before the decorated text.

+
+
+ + + +border?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +borderColor?: string | ThemeColor +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'border' for setting one or more of the individual border properties.

+
+
+ + + +borderRadius?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'border' for setting one or more of the individual border properties.

+
+
+ + + +borderSpacing?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'border' for setting one or more of the individual border properties.

+
+
+ + + +borderStyle?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'border' for setting one or more of the individual border properties.

+
+
+ + + +borderWidth?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'border' for setting one or more of the individual border properties.

+
+
+ + + +color?: string | ThemeColor +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +cursor?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +dark?: ThemableDecorationRenderOptions +
+

Overwrite options for dark themes.

+
+
+ + + +fontStyle?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +fontWeight?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +gutterIconPath?: string | Uri +
+

An absolute path or an URI to an image to be rendered in the gutter.

+
+
+ + + +gutterIconSize?: string +
+

Specifies the size of the gutter icon. +Available values are 'auto', 'contain', 'cover' and any percentage value. +For further information: https://msdn.microsoft.com/en-us/library/jj127316(v=vs.85).aspx

+
+
+ + + +isWholeLine?: boolean +
+

Should the decoration be rendered also on the whitespace after the line text. +Defaults to false.

+
+
+ + + +letterSpacing?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +light?: ThemableDecorationRenderOptions +
+

Overwrite options for light themes.

+
+
+ + + +opacity?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +outline?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +outlineColor?: string | ThemeColor +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'outline' for setting one or more of the individual outline properties.

+
+
+ + + +outlineStyle?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'outline' for setting one or more of the individual outline properties.

+
+
+ + + +outlineWidth?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'outline' for setting one or more of the individual outline properties.

+
+
+ + + +overviewRulerColor?: string | ThemeColor +
+

The color of the decoration in the overview ruler. Use rgba() and define transparent colors to play well with other decorations.

+
+
+ + + +overviewRulerLane?: OverviewRulerLane +
+

The position in the overview ruler where the decoration should be rendered.

+
+
+ + + +rangeBehavior?: DecorationRangeBehavior +
+

Customize the growing behavior of the decoration when edits occur at the edges of the decoration's range. +Defaults to DecorationRangeBehavior.OpenOpen.

+
+
+ + + +textDecoration?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ +### Definition + + + +

The definition of a symbol represented as one or many locations. +For most programming languages there is only one location at which a symbol is +defined.

+
+ + + +Definition: Location | Location[] + +### DefinitionLink + + + +

Information about where a symbol is defined.

+

Provides additional metadata over normal location definitions, including the range of +the defining symbol

+
+ + + +DefinitionLink: LocationLink + +### DefinitionProvider + + + +

The definition provider interface defines the contract between extensions and +the go to definition +and peek definition features.

+
+ +#### Methods + + + +provideDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | DefinitionLink[]> +
+

Provide the definition of the symbol at the given position and document.

+
+
+ + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Definition | DefinitionLink[]>

A definition or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined or null.

+
+
+
+ +### Diagnostic + + + +

Represents a diagnostic, such as a compiler error or warning. Diagnostic objects +are only valid in the scope of a file.

+
+ +#### Constructors + + + +new Diagnostic(range: Range, message: string, severity?: DiagnosticSeverity): Diagnostic +
+

Creates a new diagnostic object.

+
+
+ + + + + + + +
ParameterDescription
range: Range

The range to which this diagnostic applies.

+
message: string

The human-readable message.

+
severity?: DiagnosticSeverity

The severity, default is error.

+
ReturnsDescription
Diagnostic
+
+
+ +#### Properties + + + +code?: string | number +
+

A code or identifier for this diagnostic. +Should be used for later processing, e.g. when providing code actions.

+
+
+ + + +message: string +
+

The human-readable message.

+
+
+ + + +range: Range +
+

The range to which this diagnostic applies.

+
+
+ + + +relatedInformation?: DiagnosticRelatedInformation[] +
+

An array of related diagnostic information, e.g. when symbol-names within +a scope collide all definitions can be marked via this property.

+
+
+ + + +severity: DiagnosticSeverity +
+

The severity, default is error.

+
+
+ + + +source?: string +
+

A human-readable string describing the source of this +diagnostic, e.g. 'typescript' or 'super lint'.

+
+
+ + + +tags?: DiagnosticTag[] +
+

Additional metadata about the diagnostic.

+
+
+ +### DiagnosticChangeEvent + + + +

The event that is fired when diagnostics change.

+
+ +#### Properties + + + +uris: Uri[] +
+

An array of resources for which diagnostics have changed.

+
+
+ +### DiagnosticCollection + + + +

A diagnostics collection is a container that manages a set of +diagnostics. Diagnostics are always scopes to a +diagnostics collection and a resource.

+

To get an instance of a DiagnosticCollection use +createDiagnosticCollection.

+
+ +#### Properties + + + +name: string +
+

The name of this diagnostic collection, for instance typescript. Every diagnostic +from this collection will be associated with this name. Also, the task framework uses this +name when defining problem matchers.

+
+
+ +#### Methods + + + +clear(): void +
+

Remove all diagnostics from this collection. The same +as calling #set(undefined);

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +delete(uri: Uri): void +
+

Remove all diagnostics from this collection that belong +to the provided uri. The same as #set(uri, undefined).

+
+
+ + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
ReturnsDescription
void
+
+
+ + + +dispose(): void +
+

Dispose and free associated resources. Calls +clear.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +forEach(callback: (uri: Uri, diagnostics: Diagnostic[], collection: DiagnosticCollection) => any, thisArg?: any): void +
+

Iterate over each entry in this collection.

+
+
+ + + + + + +
ParameterDescription
callback: (uri: Uri, diagnostics: Diagnostic[], collection: DiagnosticCollection) => any

Function to execute for each entry.

+
thisArg?: any

The this context used when invoking the handler function.

+
ReturnsDescription
void
+
+
+ + + +get(uri: Uri): Diagnostic[] | undefined +
+

Get the diagnostics for a given resource. Note that you cannot +modify the diagnostics-array returned from this call.

+
+
+ + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
ReturnsDescription
Diagnostic[] | undefined

An immutable array of diagnostics or undefined.

+
+
+
+ + + +has(uri: Uri): boolean +
+

Check if this collection contains diagnostics for a +given resource.

+
+
+ + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
ReturnsDescription
boolean

true if this collection has diagnostic for the given resource.

+
+
+
+ + + +set(uri: Uri, diagnostics: Diagnostic[] | undefined): void +
+

Assign diagnostics for given resource. Will replace +existing diagnostics for that resource.

+
+
+ + + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
diagnostics: Diagnostic[] | undefined

Array of diagnostics or undefined

+
ReturnsDescription
void
+
+
+ + + +set(entries: [Uri, Diagnostic[] | undefined][]): void +
+

Replace all entries in this collection.

+

Diagnostics of multiple tuples of the same uri will be merged, e.g +[[file1, [d1]], [file1, [d2]]] is equivalent to [[file1, [d1, d2]]]. +If a diagnostics item is undefined as in [file1, undefined] +all previous but not subsequent diagnostics are removed.

+
+
+ + + + + +
ParameterDescription
entries: [Uri, Diagnostic[] | undefined][]

An array of tuples, like [[file1, [d1, d2]], [file2, [d3, d4, d5]]], or undefined.

+
ReturnsDescription
void
+
+
+ +### DiagnosticRelatedInformation + + + +

Represents a related message and source code location for a diagnostic. This should be +used to point to code locations that cause or related to a diagnostics, e.g when duplicating +a symbol in a scope.

+
+ +#### Constructors + + + +new DiagnosticRelatedInformation(location: Location, message: string): DiagnosticRelatedInformation +
+

Creates a new related diagnostic information object.

+
+
+ + + + + + +
ParameterDescription
location: Location

The location.

+
message: string

The message.

+
ReturnsDescription
DiagnosticRelatedInformation
+
+
+ +#### Properties + + + +location: Location +
+

The location of this related diagnostic information.

+
+
+ + + +message: string +
+

The message of this related diagnostic information.

+
+
+ +### DiagnosticSeverity + + + +

Represents the severity of diagnostics.

+
+ +#### Enumeration members + + + +Error +
+0 +
+ + + +Hint +
+3 +
+ + + +Information +
+2 +
+ + + +Warning +
+1 +
+ +### DiagnosticTag + + + +

Additional metadata about the type of a diagnostic.

+
+ +#### Enumeration members + + + +Unnecessary +
+1 +
+ +### Disposable + + + +

Represents a type which can release resources, such +as event listening or a timer.

+
+ +#### Static + + + +from(...disposableLikes: {dispose: () => any}[]): Disposable +
+

Combine many disposable-likes into one. Use this method +when having objects with a dispose function which are not +instances of Disposable.

+
+
+ + + + + +
ParameterDescription
...disposableLikes: {dispose: () => any}[]

Objects that have at least a dispose-function member.

+
ReturnsDescription
Disposable

Returns a new disposable which, upon dispose, will +dispose all provided disposables.

+
+
+
+ +#### Constructors + + + +new Disposable(callOnDispose: Function): Disposable +
+

Creates a new Disposable calling the provided function +on dispose.

+
+
+ + + + + +
ParameterDescription
callOnDispose: Function

Function that disposes something.

+
ReturnsDescription
Disposable
+
+
+ +#### Methods + + + +dispose(): any +
+

Dispose this object.

+
+
+ + + +
ReturnsDescription
any
+
+
+ +### DocumentColorProvider + + + +

The document color provider defines the contract between extensions and feature of +picking and modifying colors in the editor.

+
+ +#### Methods + + + +provideColorPresentations(color: Color, context: {document: TextDocument, range: Range}, token: CancellationToken): ProviderResult<ColorPresentation[]> +
+

Provide representations for a color.

+
+
+ + + + + + + +
ParameterDescription
color: Color

The color to show and insert.

+
context: {document: TextDocument, range: Range}

A context object with additional information

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<ColorPresentation[]>

An array of color presentations or a thenable that resolves to such. The lack of a result +can be signaled by returning undefined, null, or an empty array.

+
+
+
+ + + +provideDocumentColors(document: TextDocument, token: CancellationToken): ProviderResult<ColorInformation[]> +
+

Provide colors for the given document.

+
+
+ + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<ColorInformation[]>

An array of color information or a thenable that resolves to such. The lack of a result +can be signaled by returning undefined, null, or an empty array.

+
+
+
+ +### DocumentFilter + + + +

A document filter denotes a document by different properties like +the language, the scheme of +its resource, or a glob-pattern that is applied to the path.

+
    +
  • sample - A language filter that applies to typescript files on disk: { language: 'typescript', scheme: 'file' }
    • +
+
    +
  • sample - A language filter that applies to all package.json paths: { language: 'json', scheme: 'untitled', pattern: '**/package.json' }
    • +
+
+ +#### Properties + + + +language?: string +
+

A language id, like typescript.

+
+
+ + + +pattern?: GlobPattern +
+

A glob pattern that is matched on the absolute path of the document. Use a relative pattern +to filter documents to a workspace folder.

+
+
+ + + +scheme?: string +
+

A Uri scheme, like file or untitled.

+
+
+ +### DocumentFormattingEditProvider + + + +

The document formatting provider interface defines the contract between extensions and +the formatting-feature.

+
+ +#### Methods + + + +provideDocumentFormattingEdits(document: TextDocument, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]> +
+

Provide formatting edits for a whole document.

+
+
+ + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
options: FormattingOptions

Options controlling formatting.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<TextEdit[]>

A set of text edits or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined, null, or an empty array.

+
+
+
+ +### DocumentHighlight + + + +

A document highlight is a range inside a text document which deserves +special attention. Usually a document highlight is visualized by changing +the background color of its range.

+
+ +#### Constructors + + + +new DocumentHighlight(range: Range, kind?: DocumentHighlightKind): DocumentHighlight +
+

Creates a new document highlight object.

+
+
+ + + + + + +
ParameterDescription
range: Range

The range the highlight applies to.

+
kind?: DocumentHighlightKind

The highlight kind, default is text.

+
ReturnsDescription
DocumentHighlight
+
+
+ +#### Properties + + + +kind?: DocumentHighlightKind +
+

The highlight kind, default is text.

+
+
+ + + +range: Range +
+

The range this highlight applies to.

+
+
+ +### DocumentHighlightKind + + + +

A document highlight kind.

+
+ +#### Enumeration members + + + +Read +
+1 +
+ + + +Text +
+0 +
+ + + +Write +
+2 +
+ +### DocumentHighlightProvider + + + +

The document highlight provider interface defines the contract between extensions and +the word-highlight-feature.

+
+ +#### Methods + + + +provideDocumentHighlights(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<DocumentHighlight[]> +
+

Provide a set of document highlights, like all occurrences of a variable or +all exit-points of a function.

+
+
+ + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<DocumentHighlight[]>

An array of document highlights or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined, null, or an empty array.

+
+
+
+ +### DocumentLink + + + +

A document link is a range in a text document that links to an internal or external resource, like another +text document or a web site.

+
+ +#### Constructors + + + +new DocumentLink(range: Range, target?: Uri): DocumentLink +
+

Creates a new document link.

+
+
+ + + + + + +
ParameterDescription
range: Range

The range the document link applies to. Must not be empty.

+
target?: Uri

The uri the document link points to.

+
ReturnsDescription
DocumentLink
+
+
+ +#### Properties + + + +range: Range +
+

The range this link applies to.

+
+
+ + + +target?: Uri +
+

The uri this link points to.

+
+
+ +### DocumentLinkProvider + + + +

The document link provider defines the contract between extensions and feature of showing +links in the editor.

+
+ +#### Methods + + + +provideDocumentLinks(document: TextDocument, token: CancellationToken): ProviderResult<DocumentLink[]> +
+

Provide links for the given document. Note that the editor ships with a default provider that detects +http(s) and file links.

+
+
+ + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<DocumentLink[]>

An array of document links or a thenable that resolves to such. The lack of a result +can be signaled by returning undefined, null, or an empty array.

+
+
+
+ + + +resolveDocumentLink(link: DocumentLink, token: CancellationToken): ProviderResult<DocumentLink> +
+

Given a link fill in its target. This method is called when an incomplete +link is selected in the UI. Providers can implement this method and return incomplete links +(without target) from the provideDocumentLinks method which +often helps to improve performance.

+
+
+ + + + + + +
ParameterDescription
link: DocumentLink

The link that is to be resolved.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<DocumentLink>
+
+
+ +### DocumentRangeFormattingEditProvider + + + +

The document formatting provider interface defines the contract between extensions and +the formatting-feature.

+
+ +#### Methods + + + +provideDocumentRangeFormattingEdits(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]> +
+

Provide formatting edits for a range in a document.

+

The given range is a hint and providers can decide to format a smaller +or larger range. Often this is done by adjusting the start and end +of the range to full syntax nodes.

+
+
+ + + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
range: Range

The range which should be formatted.

+
options: FormattingOptions

Options controlling formatting.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<TextEdit[]>

A set of text edits or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined, null, or an empty array.

+
+
+
+ +### DocumentSelector + + + +

A language selector is the combination of one or many language identifiers +and language filters.

+

Note that a document selector that is just a language identifier selects all +documents, even those that are not saved on disk. Only use such selectors when +a feature works without further context, e.g without the need to resolve related +'files'.

+
    +
  • sample - let sel:DocumentSelector = { scheme: 'file', language: 'typescript' };
    • +
+
+ + + +DocumentSelector: DocumentFilter | string | Array<DocumentFilter | string> + +### DocumentSymbol + + + +

Represents programming constructs like variables, classes, interfaces etc. that appear in a document. Document +symbols can be hierarchical and they have two ranges: one that encloses its definition and one that points to +its most interesting range, e.g. the range of an identifier.

+
+ +#### Constructors + + + +new DocumentSymbol(name: string, detail: string, kind: SymbolKind, range: Range, selectionRange: Range): DocumentSymbol +
+

Creates a new document symbol.

+
+
+ + + + + + + + + +
ParameterDescription
name: string

The name of the symbol.

+
detail: string

Details for the symbol.

+
kind: SymbolKind

The kind of the symbol.

+
range: Range

The full range of the symbol.

+
selectionRange: Range

The range that should be reveal.

+
ReturnsDescription
DocumentSymbol
+
+
+ +#### Properties + + + +children: DocumentSymbol[] +
+

Children of this symbol, e.g. properties of a class.

+
+
+ + + +detail: string +
+

More detail for this symbol, e.g the signature of a function.

+
+
+ + + +kind: SymbolKind +
+

The kind of this symbol.

+
+
+ + + +name: string +
+

The name of this symbol.

+
+
+ + + +range: Range +
+

The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g comments and code.

+
+
+ + + +selectionRange: Range +
+

The range that should be selected and reveal when this symbol is being picked, e.g the name of a function. +Must be contained by the range.

+
+
+ +### DocumentSymbolProvider + + + +

The document symbol provider interface defines the contract between extensions and +the go to symbol-feature.

+
+ +#### Methods + + + +provideDocumentSymbols(document: TextDocument, token: CancellationToken): ProviderResult<SymbolInformation[] | DocumentSymbol[]> +
+

Provide symbol information for the given document.

+
+
+ + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<SymbolInformation[] | DocumentSymbol[]>

An array of document highlights or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined, null, or an empty array.

+
+
+
+ +### DocumentSymbolProviderMetadata + + + +

Metadata about a document symbol provider.

+
+ +#### Properties + + + +label?: string +
+

A human readable string that is shown when multiple outlines trees show for one document.

+
+
+ +### EndOfLine + + + +

Represents an end of line character sequence in a document.

+
+ +#### Enumeration members + + + +CRLF +
+2 +
+ + + +LF +
+1 +
+ +### EnterAction + + + +

Describes what to do when pressing Enter.

+
+ +#### Properties + + + +appendText?: string +
+

Describes text to be appended after the new line and after the indentation.

+
+
+ + + +indentAction: IndentAction +
+

Describe what to do with the indentation.

+
+
+ + + +removeText?: number +
+

Describes the number of characters to remove from the new line's indentation.

+
+
+ +### Event<T> + + + +

Represents a typed event.

+

A function that represents an event to which you subscribe by calling it with +a listener function as argument.

+
    +
  • sample - item.onDidChange(function(event) { console.log("Event happened: " + event); });
    • +
+
+ + + +(listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable +
+

A function that represents an event to which you subscribe by calling it with +a listener function as argument.

+

A function that represents an event to which you subscribe by calling it with +a listener function as argument.

+
+
+ + + + + + + +
ParameterDescription
listener: (e: T) => any

The listener function will be called when the event happens.

+
thisArgs?: any

The this-argument which will be used when calling the event listener.

+
disposables?: Disposable[]

An array to which a disposable will be added.

+
ReturnsDescription
Disposable

A disposable which unsubscribes the event listener.

+
+
+
+ +### EventEmitter<T> + + + +

An event emitter can be used to create and manage an event for others +to subscribe to. One emitter always owns one event.

+

Use this class if you want to provide event from within your extension, for instance +inside a TextDocumentContentProvider or when providing +API to other extensions.

+
+ +#### Properties + + + +event: Event<T> +
+

The event listeners can subscribe to.

+
+
+ +#### Methods + + + +dispose(): void +
+

Dispose this object and free resources.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +fire(data?: T): void +
+

Notify all subscribers of the event. Failure +of one or more listener will not fail this function call.

+
+
+ + + + + +
ParameterDescription
data?: T

The event object.

+
ReturnsDescription
void
+
+
+ +### Extension<T> + + + +

Represents an extension.

+

To get an instance of an Extension use getExtension.

+
+ +#### Properties + + + +exports: T +
+

The public API exported by this extension. It is an invalid action +to access this field before this extension has been activated.

+
+
+ + + +extensionPath: string +
+

The absolute file path of the directory containing this extension.

+
+
+ + + +id: string +
+

The canonical extension identifier in the form of: publisher.name.

+
+
+ + + +isActive: boolean +
+

true if the extension has been activated.

+
+
+ + + +packageJSON: any +
+

The parsed contents of the extension's package.json.

+
+
+ +#### Methods + + + +activate(): Thenable<T> +
+

Activates this extension and returns its public API.

+
+
+ + + +
ReturnsDescription
Thenable<T>

A promise that will resolve when this extension has been activated.

+
+
+
+ +### ExtensionContext + + + +

An extension context is a collection of utilities private to an +extension.

+

An instance of an ExtensionContext is provided as the first +parameter to the activate-call of an extension.

+
+ +#### Properties + + + +extensionPath: string +
+

The absolute file path of the directory containing the extension.

+
+
+ + + +globalState: Memento +
+

A memento object that stores state independent +of the current opened workspace.

+
+
+ + + +logPath: string +
+

An absolute file path of a directory in which the extension can create log files. +The directory might not exist on disk and creation is up to the extension. However, +the parent directory is guaranteed to be existent.

+
+
+ + + +storagePath: string | undefined +
+

An absolute file path of a workspace specific directory in which the extension +can store private state. The directory might not exist on disk and creation is +up to the extension. However, the parent directory is guaranteed to be existent.

+

Use workspaceState or +globalState to store key value data.

+
+
+ + + +subscriptions: {dispose}[] +
+

An array to which disposables can be added. When this +extension is deactivated the disposables will be disposed.

+
+
+ + + +workspaceState: Memento +
+

A memento object that stores state in the context +of the currently opened workspace.

+
+
+ +#### Methods + + + +asAbsolutePath(relativePath: string): string +
+

Get the absolute path of a resource contained in the extension.

+
+
+ + + + + +
ParameterDescription
relativePath: string

A relative path to a resource contained in the extension.

+
ReturnsDescription
string

The absolute path of the resource.

+
+
+
+ +### FileChangeEvent + + + +

The event filesystem providers must use to signal a file change.

+
+ +#### Properties + + + +type: FileChangeType +
+

The type of change.

+
+
+ + + +uri: Uri +
+

The uri of the file that has changed.

+
+
+ +### FileChangeType + + + +

Enumeration of file change types.

+
+ +#### Enumeration members + + + +Changed +
+1 +
+ + + +Created +
+2 +
+ + + +Deleted +
+3 +
+ +### FileStat + + + +

The FileStat-type represents metadata about a file

+
+ +#### Properties + + + +ctime: number +
+

The creation timestamp in milliseconds elapsed since January 1, 1970 00:00:00 UTC.

+
+
+ + + +mtime: number +
+

The modification timestamp in milliseconds elapsed since January 1, 1970 00:00:00 UTC.

+
+
+ + + +size: number +
+

The size in bytes.

+
+
+ + + +type: FileType +
+

The type of the file, e.g. is a regular file, a directory, or symbolic link +to a file.

+
+
+ +### FileSystemError + + + +

A type that filesystem providers should use to signal errors.

+

This class has factory methods for common error-cases, like EntryNotFound when +a file or folder doesn't exist, use them like so: throw vscode.FileSystemError.EntryNotFound(someUri);

+
+ +#### Static + + + +Error: ErrorConstructor +
+
+
+ + + +message: string +
+
+
+ + + +name: string +
+
+
+ + + +stack?: string +
+
+
+ + + +FileExists(messageOrUri?: string | Uri): FileSystemError +
+

Create an error to signal that a file or folder already exists, e.g. when +creating but not overwriting a file.

+
+
+ + + + + +
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

+
ReturnsDescription
FileSystemError
+
+
+ + + +FileIsADirectory(messageOrUri?: string | Uri): FileSystemError +
+

Create an error to signal that a file is a folder.

+
+
+ + + + + +
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

+
ReturnsDescription
FileSystemError
+
+
+ + + +FileNotADirectory(messageOrUri?: string | Uri): FileSystemError +
+

Create an error to signal that a file is not a folder.

+
+
+ + + + + +
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

+
ReturnsDescription
FileSystemError
+
+
+ + + +FileNotFound(messageOrUri?: string | Uri): FileSystemError +
+

Create an error to signal that a file or folder wasn't found.

+
+
+ + + + + +
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

+
ReturnsDescription
FileSystemError
+
+
+ + + +NoPermissions(messageOrUri?: string | Uri): FileSystemError +
+

Create an error to signal that an operation lacks required permissions.

+
+
+ + + + + +
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

+
ReturnsDescription
FileSystemError
+
+
+ + + +Unavailable(messageOrUri?: string | Uri): FileSystemError +
+

Create an error to signal that the file system is unavailable or too busy to +complete a request.

+
+
+ + + + + +
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

+
ReturnsDescription
FileSystemError
+
+
+ +#### Constructors + + + +new FileSystemError(messageOrUri?: string | Uri): FileSystemError +
+

Creates a new filesystem error.

+
+
+ + + + + +
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

+
ReturnsDescription
FileSystemError
+
+
+ +### FileSystemProvider + + + +

The filesystem provider defines what the editor needs to read, write, discover, +and to manage files and folders. It allows extensions to serve files from remote places, +like ftp-servers, and to seamlessly integrate those into the editor.

+
    +
  • Note 1: The filesystem provider API works with uris and assumes hierarchical +paths, e.g. foo:/my/path is a child of foo:/my/ and a parent of foo:/my/path/deeper.
    • +
  • Note 2: There is an activation event onFileSystem:<scheme> that fires when a file +or folder is being accessed.
    • +
  • Note 3: The word 'file' is often used to denote all kinds of files, e.g. +folders, symbolic links, and regular files.
    • +
+
+ +#### Events + + + +onDidChangeFile: Event<FileChangeEvent[]> +
+

An event to signal that a resource has been created, changed, or deleted. This +event should fire for resources that are being watched +by clients of this provider.

+
+
+ +#### Methods + + + +copy(source: Uri, destination: Uri, options: {overwrite: boolean}): void | Thenable<void> +
+

Copy files or folders. Implementing this function is optional but it will speedup +the copy operation.

+ +
    +
  • throws - FileNotFound when parent of destination doesn't exist, e.g. no mkdirp-logic required.
    • +
+
    +
  • throws - FileExists when destination exists and when the overwrite option is not true.
    • +
+ +
+
+ + + + + + + +
ParameterDescription
source: Uri

The existing file.

+
destination: Uri

The destination location.

+
options: {overwrite: boolean}

Defines if existing files should be overwriten.

+
ReturnsDescription
void | Thenable<void>
+
+
+ + + +createDirectory(uri: Uri): void | Thenable<void> +
+

Create a new directory (Note, that new files are created via write-calls).

+
    +
  • throws - FileNotFound when the parent of uri doesn't exist, e.g. no mkdirp-logic required.
    • +
+ + +
+
+ + + + + +
ParameterDescription
uri: Uri

The uri of the new folder.

+
ReturnsDescription
void | Thenable<void>
+
+
+ + + +delete(uri: Uri, options: {recursive: boolean}): void | Thenable<void> +
+

Delete a file.

+ + +
+
+ + + + + + +
ParameterDescription
uri: Uri

The resource that is to be deleted.

+
options: {recursive: boolean}

Defines if deletion of folders is recursive.

+
ReturnsDescription
void | Thenable<void>
+
+
+ + + +readDirectory(uri: Uri): [string, FileType][] | Thenable<[string, FileType][]> +
+

Retrieve all entries of a directory.

+ +
+
+ + + + + +
ParameterDescription
uri: Uri

The uri of the folder.

+
ReturnsDescription
[string, FileType][] | Thenable<[string, FileType][]>

An array of name/type-tuples or a thenable that resolves to such.

+
+
+
+ + + +readFile(uri: Uri): Uint8Array | Thenable<Uint8Array> +
+

Read the entire contents of a file.

+ +
+
+ + + + + +
ParameterDescription
uri: Uri

The uri of the file.

+
ReturnsDescription
Uint8Array | Thenable<Uint8Array>

An array of bytes or a thenable that resolves to such.

+
+
+
+ + + +rename(oldUri: Uri, newUri: Uri, options: {overwrite: boolean}): void | Thenable<void> +
+

Rename a file or folder.

+ +
    +
  • throws - FileNotFound when parent of newUri doesn't exist, e.g. no mkdirp-logic required.
    • +
+
    +
  • throws - FileExists when newUri exists and when the overwrite option is not true.
    • +
+ +
+
+ + + + + + + +
ParameterDescription
oldUri: Uri

The existing file.

+
newUri: Uri

The new location.

+
options: {overwrite: boolean}

Defines if existing files should be overwritten.

+
ReturnsDescription
void | Thenable<void>
+
+
+ + + +stat(uri: Uri): FileStat | Thenable<FileStat> +
+

Retrieve metadata about a file.

+

Note that the metadata for symbolic links should be the metadata of the file they refer to. +Still, the SymbolicLink-type must be used in addition to the actual type, e.g. +FileType.SymbolicLink | FileType.Directory.

+ +
+
+ + + + + +
ParameterDescription
uri: Uri

The uri of the file to retrieve metadata about.

+
ReturnsDescription
FileStat | Thenable<FileStat>

The file metadata about the file.

+
+
+
+ + + +watch(uri: Uri, options: {excludes: string[], recursive: boolean}): Disposable +
+

Subscribe to events in the file or folder denoted by uri.

+

The editor will call this function for files and folders. In the latter case, the +options differ from defaults, e.g. what files/folders to exclude from watching +and if subfolders, sub-subfolder, etc. should be watched (recursive).

+
+
+ + + + + + +
ParameterDescription
uri: Uri

The uri of the file to be watched.

+
options: {excludes: string[], recursive: boolean}

Configures the watch.

+
ReturnsDescription
Disposable

A disposable that tells the provider to stop watching the uri.

+
+
+
+ + + +writeFile(uri: Uri, content: Uint8Array, options: {create: boolean, overwrite: boolean}): void | Thenable<void> +
+

Write data to a file, replacing its entire contents.

+
    +
  • throws - FileNotFound when uri doesn't exist and create is not set.
    • +
+
    +
  • throws - FileNotFound when the parent of uri doesn't exist and create is set, e.g. no mkdirp-logic required.
    • +
+
    +
  • throws - FileExists when uri already exists, create is set but overwrite is not set.
    • +
+ +
+
+ + + + + + + +
ParameterDescription
uri: Uri

The uri of the file.

+
content: Uint8Array

The new content of the file.

+
options: {create: boolean, overwrite: boolean}

Defines if missing files should or must be created.

+
ReturnsDescription
void | Thenable<void>
+
+
+ +### FileSystemWatcher + + + +

A file system watcher notifies about changes to files and folders +on disk.

+

To get an instance of a FileSystemWatcher use +createFileSystemWatcher.

+
+ +#### Events + + + +onDidChange: Event<Uri> +
+

An event which fires on file/folder change.

+
+
+ + + +onDidCreate: Event<Uri> +
+

An event which fires on file/folder creation.

+
+
+ + + +onDidDelete: Event<Uri> +
+

An event which fires on file/folder deletion.

+
+
+ +#### Static + + + +from(...disposableLikes: {dispose: () => any}[]): Disposable +
+

Combine many disposable-likes into one. Use this method +when having objects with a dispose function which are not +instances of Disposable.

+
+
+ + + + + +
ParameterDescription
...disposableLikes: {dispose: () => any}[]

Objects that have at least a dispose-function member.

+
ReturnsDescription
Disposable

Returns a new disposable which, upon dispose, will +dispose all provided disposables.

+
+
+
+ +#### Constructors + + + +new FileSystemWatcher(callOnDispose: Function): FileSystemWatcher +
+

Creates a new Disposable calling the provided function +on dispose.

+
+
+ + + + + +
ParameterDescription
callOnDispose: Function

Function that disposes something.

+
ReturnsDescription
FileSystemWatcher
+
+
+ +#### Properties + + + +ignoreChangeEvents: boolean +
+

true if this file system watcher has been created such that +it ignores change file system events.

+
+
+ + + +ignoreCreateEvents: boolean +
+

true if this file system watcher has been created such that +it ignores creation file system events.

+
+
+ + + +ignoreDeleteEvents: boolean +
+

true if this file system watcher has been created such that +it ignores delete file system events.

+
+
+ +#### Methods + + + +dispose(): any +
+

Dispose this object.

+
+
+ + + +
ReturnsDescription
any
+
+
+ +### FileType + + + +

Enumeration of file types. The types File and Directory can also be +a symbolic links, in that use FileType.File | FileType.SymbolicLink and +FileType.Directory | FileType.SymbolicLink.

+
+ +#### Enumeration members + + + +Directory +
+2 +
+ + + +File +
+1 +
+ + + +SymbolicLink +
+64 +
+ + + +Unknown +
+0 +
+ +### FoldingContext + + + +

Folding context (for future use)

+
+ +### FoldingRange + + + +

A line based folding range. To be valid, start and end line must a zero or larger and smaller than the number of lines in the document. +Invalid ranges will be ignored.

+
+ +#### Constructors + + + +new FoldingRange(start: number, end: number, kind?: FoldingRangeKind): FoldingRange +
+

Creates a new folding range.

+
+
+ + + + + + + +
ParameterDescription
start: number

The start line of the folded range.

+
end: number

The end line of the folded range.

+
kind?: FoldingRangeKind

The kind of the folding range.

+
ReturnsDescription
FoldingRange
+
+
+ +#### Properties + + + +end: number +
+

The zero-based end line of the range to fold. The folded area ends with the line's last character. +To be valid, the end must be zero or larger and smaller than the number of lines in the document.

+
+
+ + + +kind?: FoldingRangeKind +
+

Describes the Kind of the folding range such as Comment or +Region. The kind is used to categorize folding ranges and used by commands +like 'Fold all comments'. See +FoldingRangeKind for an enumeration of all kinds. +If not set, the range is originated from a syntax element.

+
+
+ + + +start: number +
+

The zero-based start line of the range to fold. The folded area starts after the line's last character. +To be valid, the end must be zero or larger and smaller than the number of lines in the document.

+
+
+ +### FoldingRangeKind + + + +

An enumeration of specific folding range kinds. The kind is an optional field of a FoldingRange +and is used to distinguish specific folding ranges such as ranges originated from comments. The kind is used by commands like +Fold all comments or Fold all regions. +If the kind is not set on the range, the range originated from a syntax element other than comments, imports or region markers.

+
+ +#### Enumeration members + + + +Comment +
+1 +
+ + + +Imports +
+2 +
+ + + +Region +
+3 +
+ +### FoldingRangeProvider + + + +

The folding range provider interface defines the contract between extensions and +Folding in the editor.

+
+ +#### Methods + + + +provideFoldingRanges(document: TextDocument, context: FoldingContext, token: CancellationToken): ProviderResult<FoldingRange[]> +
+

Returns a list of folding ranges or null and undefined if the provider +does not want to participate or was cancelled.

+
+
+ + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
context: FoldingContext

Additional context information (for future use)

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<FoldingRange[]>
+
+
+ +### FormattingOptions + + + +

Value-object describing what options formatting should use.

+
+ +#### Properties + + + +insertSpaces: boolean +
+

Prefer spaces over tabs.

+
+
+ + + +tabSize: number +
+

Size of a tab in spaces.

+
+
+ +### FunctionBreakpoint + + + +

A breakpoint specified by a function name.

+
+ +#### Constructors + + + +new FunctionBreakpoint(functionName: string, enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): FunctionBreakpoint +
+

Create a new function breakpoint.

+
+
+ + + + + + + + + +
ParameterDescription
functionName: string
enabled?: boolean
condition?: string
hitCondition?: string
logMessage?: string
ReturnsDescription
FunctionBreakpoint
+
+
+ +#### Properties + + + +condition?: string +
+

An optional expression for conditional breakpoints.

+
+
+ + + +enabled: boolean +
+

Is breakpoint enabled.

+
+
+ + + +functionName: string +
+

The name of the function to which this breakpoint is attached.

+
+
+ + + +hitCondition?: string +
+

An optional expression that controls how many hits of the breakpoint are ignored.

+
+
+ + + +id: string +
+

The unique ID of the breakpoint.

+
+
+ + + +logMessage?: string +
+

An optional message that gets logged when this breakpoint is hit. Embedded expressions within {} are interpolated by the debug adapter.

+
+
+ +### GlobPattern + + + +

A file glob pattern to match file paths against. This can either be a glob pattern string +(like **/*.{ts,js} or *.{ts,js}) or a relative pattern.

+

Glob patterns can have the following syntax:

+
    +
  • * to match one or more characters in a path segment
    • +
  • ? to match on one character in a path segment
    • +
  • ** to match any number of path segments, including none
    • +
  • {} to group conditions (e.g. **/*.{ts,js} matches all TypeScript and JavaScript files)
    • +
  • [] to declare a range of characters to match in a path segment (e.g., example.[0-9] to match on example.0, example.1, …)
    • +
  • [!...] to negate a range of characters to match in a path segment (e.g., example.[!0-9] to match on example.a, example.b, but not example.0)
    • +
+
+ + + +GlobPattern: string | RelativePattern + +### Hover + + + +

A hover represents additional information for a symbol or word. Hovers are +rendered in a tooltip-like widget.

+
+ +#### Constructors + + + +new Hover(contents: MarkedString | MarkedString[], range?: Range): Hover +
+

Creates a new hover object.

+
+
+ + + + + + +
ParameterDescription
contents: MarkedString | MarkedString[]

The contents of the hover.

+
range?: Range

The range to which the hover applies.

+
ReturnsDescription
Hover
+
+
+ +#### Properties + + + +contents: MarkedString[] +
+

The contents of this hover.

+
+
+ + + +range?: Range +
+

The range to which this hover applies. When missing, the +editor will use the range at the current position or the +current position itself.

+
+
+ +### HoverProvider + + + +

The hover provider interface defines the contract between extensions and +the hover-feature.

+
+ +#### Methods + + + +provideHover(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Hover> +
+

Provide a hover for the given position and document. Multiple hovers at the same +position will be merged by the editor. A hover can have a range which defaults +to the word range at the position when omitted.

+
+
+ + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Hover>

A hover or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined or null.

+
+
+
+ +### ImplementationProvider + + + +

The implementation provider interface defines the contract between extensions and +the go to implementation feature.

+
+ +#### Methods + + + +provideImplementation(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | DefinitionLink[]> +
+

Provide the implementations of the symbol at the given position and document.

+
+
+ + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Definition | DefinitionLink[]>

A definition or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined or null.

+
+
+
+ +### IndentAction + + + +

Describes what to do with the indentation when pressing Enter.

+
+ +#### Enumeration members + + + +Indent +
+1 +
+ + + +IndentOutdent +
+2 +
+ + + +None +
+0 +
+ + + +Outdent +
+3 +
+ +### IndentationRule + + + +

Describes indentation rules for a language.

+
+ +#### Properties + + + +decreaseIndentPattern: RegExp +
+

If a line matches this pattern, then all the lines after it should be unindented once (until another rule matches).

+
+
+ + + +increaseIndentPattern: RegExp +
+

If a line matches this pattern, then all the lines after it should be indented once (until another rule matches).

+
+
+ + + +indentNextLinePattern?: RegExp +
+

If a line matches this pattern, then only the next line after it should be indented once.

+
+
+ + + +unIndentedLinePattern?: RegExp +
+

If a line matches this pattern, then its indentation should not be changed and it should not be evaluated against the other rules.

+
+
+ +### InputBox + + + +

A concrete QuickInput to let the user input a text value.

+

Note that in many cases the more convenient window.showInputBox +is easier to use. window.createInputBox should be used +when window.showInputBox does not offer the required flexibility.

+
+ +#### Events + + + +onDidAccept: Event<void> +
+

An event signaling when the user indicated acceptance of the input value.

+
+
+ + + +onDidChangeValue: Event<string> +
+

An event signaling when the value has changed.

+
+
+ + + +onDidHide: Event<void> +
+

An event signaling when this input UI is hidden.

+

There are several reasons why this UI might have to be hidden and +the extension will be notified through QuickInput.onDidHide. +(Examples include: an explict call to QuickInput.hide, +the user pressing Esc, some other input UI opening, etc.)

+
+
+ + + +onDidTriggerButton: Event<QuickInputButton> +
+

An event signaling when a button was triggered.

+
+
+ +#### Properties + + + +busy: boolean +
+

If the UI should show a progress indicator. Defaults to false.

+

Change this to true, e.g., while loading more data or validating +user input.

+
+
+ + + +buttons: ReadonlyArray<QuickInputButton> +
+

Buttons for actions in the UI.

+
+
+ + + +enabled: boolean +
+

If the UI should allow for user input. Defaults to true.

+

Change this to false, e.g., while validating user input or +loading data for the next step in user input.

+
+
+ + + +ignoreFocusOut: boolean +
+

If the UI should stay open even when loosing UI focus. Defaults to false.

+
+
+ + + +password: boolean +
+

If the input value should be hidden. Defaults to false.

+
+
+ + + +placeholder: string | undefined +
+

Optional placeholder in the filter text.

+
+
+ + + +prompt: string | undefined +
+

An optional prompt text providing some ask or explanation to the user.

+
+
+ + + +step: number | undefined +
+

An optional current step count.

+
+
+ + + +title: string | undefined +
+

An optional title.

+
+
+ + + +totalSteps: number | undefined +
+

An optional total step count.

+
+
+ + + +validationMessage: string | undefined +
+

An optional validation message indicating a problem with the current input value.

+
+
+ + + +value: string +
+

Current input value.

+
+
+ +#### Methods + + + +dispose(): void +
+

Dispose of this input UI and any associated resources. If it is still +visible, it is first hidden. After this call the input UI is no longer +functional and no additional methods or properties on it should be +accessed. Instead a new input UI should be created.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +hide(): void +
+

Hides this input UI. This will also fire an QuickInput.onDidHide +event.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +show(): void +
+

Makes the input UI visible in its current configuration. Any other input +UI will first fire an QuickInput.onDidHide event.

+
+
+ + + +
ReturnsDescription
void
+
+
+ +### InputBoxOptions + + + +

Options to configure the behavior of the input box UI.

+
+ +#### Properties + + + +ignoreFocusOut?: boolean +
+

Set to true to keep the input box open when focus moves to another part of the editor or to another window.

+
+
+ + + +password?: boolean +
+

Set to true to show a password prompt that will not show the typed value.

+
+
+ + + +placeHolder?: string +
+

An optional string to show as place holder in the input box to guide the user what to type.

+
+
+ + + +prompt?: string +
+

The text to display underneath the input box.

+
+
+ + + +value?: string +
+

The value to prefill in the input box.

+
+
+ + + +valueSelection?: [number, number] +
+

Selection of the prefilled value. Defined as tuple of two number where the +first is the inclusive start index and the second the exclusive end index. When undefined the whole +word will be selected, when empty (start equals end) only the cursor will be set, +otherwise the defined range will be selected.

+
+
+ +#### Methods + + + +validateInput(value: string): string | undefined | null | Thenable<string | undefined | null> +
+

An optional function that will be called to validate input and to give a hint +to the user.

+
+
+ + + + + +
ParameterDescription
value: string

The current value of the input box.

+
ReturnsDescription
string | undefined | null | Thenable<string | undefined | null>

A human readable string which is presented as diagnostic message. +Return undefined, null, or the empty string when 'value' is valid.

+
+
+
+ +### LanguageConfiguration + + + +

The language configuration interfaces defines the contract between extensions +and various editor features, like automatic bracket insertion, automatic indentation etc.

+
+ +#### Properties + + + +__characterPairSupport?: {autoClosingPairs: {close: string, notIn: string[], open: string}[]} +
+

Deprecated Do not use.

+
    +
  • deprecated - * Use the autoClosingPairs property in the language configuration file instead.
    • +
+
+
+ + + +__electricCharacterSupport?: {brackets: any, docComment: {close: string, lineStart: string, open: string, scope: string}} +
+

Deprecated Do not use.

+
    +
  • deprecated - Will be replaced by a better API soon.
    • +
+
+
+ + + +brackets?: CharacterPair[] +
+

The language's brackets. +This configuration implicitly affects pressing Enter around these brackets.

+
+
+ + + +comments?: CommentRule +
+

The language's comment settings.

+
+
+ + + +indentationRules?: IndentationRule +
+

The language's indentation settings.

+
+
+ + + +onEnterRules?: OnEnterRule[] +
+

The language's rules to be evaluated when pressing Enter.

+
+
+ + + +wordPattern?: RegExp +
+

The language's word definition. +If the language supports Unicode identifiers (e.g. JavaScript), it is preferable +to provide a word definition that uses exclusion of known separators. +e.g.: A regex that matches anything except known separators (and dot is allowed to occur in a floating point number): + /(-?\d.\d\w)|([^`~!\@@#\%\^\&*()-\=+[{]}\|\;\:\'\"\,.\<>\/\?\s]+)/g

+
+
+ +### Location + + + +

Represents a location inside a resource, such as a line +inside a text file.

+
+ +#### Constructors + + + +new Location(uri: Uri, rangeOrPosition: Range | Position): Location +
+

Creates a new location object.

+
+
+ + + + + + +
ParameterDescription
uri: Uri

The resource identifier.

+
rangeOrPosition: Range | Position

The range or position. Positions will be converted to an empty range.

+
ReturnsDescription
Location
+
+
+ +#### Properties + + + +range: Range +
+

The document range of this location.

+
+
+ + + +uri: Uri +
+

The resource identifier of this location.

+
+
+ +### LocationLink + + + +

Represents the connection of two locations. Provides additional metadata over normal locations, +including an origin range.

+
+ +#### Properties + + + +originSelectionRange?: Range +
+

Span of the origin of this link.

+

Used as the underlined span for mouse definition hover. Defaults to the word range at +the definition position.

+
+
+ + + +targetRange: Range +
+

The full target range of this link.

+
+
+ + + +targetSelectionRange?: Range +
+

The span of this link.

+
+
+ + + +targetUri: Uri +
+

The target resource identifier of this link.

+
+
+ +### MarkdownString + + + +

The MarkdownString represents human readable text that supports formatting via the +markdown syntax. Standard markdown is supported, also tables, but no embedded html.

+
+ +#### Constructors + + + +new MarkdownString(value?: string): MarkdownString +
+

Creates a new markdown string with the given value.

+
+
+ + + + + +
ParameterDescription
value?: string

Optional, initial value.

+
ReturnsDescription
MarkdownString
+
+
+ +#### Properties + + + +isTrusted?: boolean +
+

Indicates that this markdown string is from a trusted source. Only trusted +markdown supports links that execute commands, e.g. [Run it](command:myCommandId).

+
+
+ + + +value: string +
+

The markdown string.

+
+
+ +#### Methods + + + +appendCodeblock(value: string, language?: string): MarkdownString +
+

Appends the given string as codeblock using the provided language.

+
+
+ + + + + + +
ParameterDescription
value: string

A code snippet.

+
language?: string

An optional language identifier.

+
ReturnsDescription
MarkdownString
+
+
+ + + +appendMarkdown(value: string): MarkdownString +
+

Appends the given string 'as is' to this markdown string.

+
+
+ + + + + +
ParameterDescription
value: string

Markdown string.

+
ReturnsDescription
MarkdownString
+
+
+ + + +appendText(value: string): MarkdownString +
+

Appends and escapes the given string to this markdown string.

+
+
+ + + + + +
ParameterDescription
value: string

Plain text.

+
ReturnsDescription
MarkdownString
+
+
+ +### MarkedString + + + +

MarkedString can be used to render human readable text. It is either a markdown string +or a code-block that provides a language and a code snippet. Note that +markdown strings will be sanitized - that means html will be escaped.

+
    +
  • deprecated - This type is deprecated, please use MarkdownString instead.
    • +
+
+ + + +MarkedString: MarkdownString | string | {language: string, value: string} + +### Memento + + + +

A memento represents a storage utility. It can store and retrieve +values.

+
+ +#### Methods + + + +get<T>(key: string): T | undefined +
+

Return a value.

+
+
+ + + + + +
ParameterDescription
key: string

A string.

+
ReturnsDescription
T | undefined

The stored value or undefined.

+
+
+
+ + + +get<T>(key: string, defaultValue: T): T +
+

Return a value.

+
+
+ + + + + + +
ParameterDescription
key: string

A string.

+
defaultValue: T

A value that should be returned when there is no +value (undefined) with the given key.

+
ReturnsDescription
T

The stored value or the defaultValue.

+
+
+
+ + + +update(key: string, value: any): Thenable<void> +
+

Store a value. The value must be JSON-stringifyable.

+
+
+ + + + + + +
ParameterDescription
key: string

A string.

+
value: any

A value. MUST not contain cyclic references.

+
ReturnsDescription
Thenable<void>
+
+
+ +### MessageItem + + + +

Represents an action that is shown with an information, warning, or +error message.

+ + + +
+ +#### Properties + + + +isCloseAffordance?: boolean +
+

A hint for modal dialogs that the item should be triggered +when the user cancels the dialog (e.g. by pressing the ESC +key).

+

Note: this option is ignored for non-modal messages.

+
+
+ + + +title: string +
+

A short title like 'Retry', 'Open Log' etc.

+
+
+ +### MessageOptions + + + +

Options to configure the behavior of the message.

+ + + +
+ +#### Properties + + + +modal?: boolean +
+

Indicates that this message should be modal.

+
+
+ +### OnEnterRule + + + +

Describes a rule to be evaluated when pressing Enter.

+
+ +#### Properties + + + +action: EnterAction +
+

The action to execute.

+
+
+ + + +afterText?: RegExp +
+

This rule will only execute if the text after the cursor matches this regular expression.

+
+
+ + + +beforeText: RegExp +
+

This rule will only execute if the text before the cursor matches this regular expression.

+
+
+ +### OnTypeFormattingEditProvider + + + +

The document formatting provider interface defines the contract between extensions and +the formatting-feature.

+
+ +#### Methods + + + +provideOnTypeFormattingEdits(document: TextDocument, position: Position, ch: string, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]> +
+

Provide formatting edits after a character has been typed.

+

The given position and character should hint to the provider +what range the position to expand to, like find the matching { +when } has been entered.

+
+
+ + + + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
ch: string

The character that has been typed.

+
options: FormattingOptions

Options controlling formatting.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<TextEdit[]>

A set of text edits or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined, null, or an empty array.

+
+
+
+ +### OpenDialogOptions + + + +

Options to configure the behaviour of a file open dialog.

+
    +
  • Note 1: A dialog can select files, folders, or both. This is not true for Windows +which enforces to open either files or folder, but not both.
    • +
  • Note 2: Explicitly setting canSelectFiles and canSelectFolders to false is futile +and the editor then silently adjusts the options to select files.
    • +
+
+ +#### Properties + + + +canSelectFiles?: boolean +
+

Allow to select files, defaults to true.

+
+
+ + + +canSelectFolders?: boolean +
+

Allow to select folders, defaults to false.

+
+
+ + + +canSelectMany?: boolean +
+

Allow to select many files or folders.

+
+
+ + + +defaultUri?: Uri +
+

The resource the dialog shows when opened.

+
+
+ + + +filters?: +
+

A set of file filters that are used by the dialog. Each entry is a human readable label, +like "TypeScript", and an array of extensions, e.g.

+ +
{
+    'Images': ['png', 'jpg']
+    'TypeScript': ['ts', 'tsx']
+}
+
+
+
+ + + +openLabel?: string +
+

A human-readable string for the open button.

+
+
+ +### OutputChannel + + + +

An output channel is a container for readonly textual information.

+

To get an instance of an OutputChannel use +createOutputChannel.

+
+ +#### Properties + + + +name: string +
+

The human-readable name of this output channel.

+
+
+ +#### Methods + + + +append(value: string): void +
+

Append the given value to the channel.

+
+
+ + + + + +
ParameterDescription
value: string

A string, falsy values will not be printed.

+
ReturnsDescription
void
+
+
+ + + +appendLine(value: string): void +
+

Append the given value and a line feed character +to the channel.

+
+
+ + + + + +
ParameterDescription
value: string

A string, falsy values will be printed.

+
ReturnsDescription
void
+
+
+ + + +clear(): void +
+

Removes all output from the channel.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +dispose(): void +
+

Dispose and free associated resources.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +hide(): void +
+

Hide this channel from the UI.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +show(preserveFocus?: boolean): void +
+

Reveal this channel in the UI.

+
+
+ + + + + +
ParameterDescription
preserveFocus?: boolean

When true the channel will not take focus.

+
ReturnsDescription
void
+
+
+ + + +show(column?: ViewColumn, preserveFocus?: boolean): void +
+

Reveal this channel in the UI.

+
    +
  • deprecated - Use the overload with just one parameter (show(preserveFocus?: boolean): void).
    • +
+
+
+ + + + + + +
ParameterDescription
column?: ViewColumn

This argument is deprecated and will be ignored.

+
preserveFocus?: boolean

When true the channel will not take focus.

+
ReturnsDescription
void
+
+
+ +### OverviewRulerLane + + + +

Represents different positions for rendering a decoration in an overview ruler. +The overview ruler supports three lanes.

+
+ +#### Enumeration members + + + +Center +
+2 +
+ + + +Full +
+7 +
+ + + +Left +
+1 +
+ + + +Right +
+4 +
+ +### ParameterInformation + + + +

Represents a parameter of a callable-signature. A parameter can +have a label and a doc-comment.

+
+ +#### Constructors + + + +new ParameterInformation(label: string | [number, number], documentation?: string | MarkdownString): ParameterInformation +
+

Creates a new parameter information object.

+
+
+ + + + + + +
ParameterDescription
label: string | [number, number]

A label string or inclusive start and exclusive end offsets within its containing signature label.

+
documentation?: string | MarkdownString

A doc string.

+
ReturnsDescription
ParameterInformation
+
+
+ +#### Properties + + + +documentation?: string | MarkdownString +
+

The human-readable doc-comment of this signature. Will be shown +in the UI but can be omitted.

+
+
+ + + +label: string | [number, number] +
+

The label of this signature.

+

Either a string or inclusive start and exclusive end offsets within its containing +signature label. Note: A label of type string must be +a substring of its containing signature information's label.

+
+
+ +### Position + + + +

Represents a line and character position, such as +the position of the cursor.

+

Position objects are immutable. Use the with or +translate methods to derive new positions +from an existing position.

+
+ +#### Constructors + + + +new Position(line: number, character: number): Position +
+
+
+ + + + + + +
ParameterDescription
line: number

A zero-based line value.

+
character: number

A zero-based character value.

+
ReturnsDescription
Position
+
+
+ +#### Properties + + + +character: number +
+

The zero-based character value.

+
+
+ + + +line: number +
+

The zero-based line value.

+
+
+ +#### Methods + + + +compareTo(other: Position): number +
+

Compare this to other.

+
+
+ + + + + +
ParameterDescription
other: Position

A position.

+
ReturnsDescription
number

A number smaller than zero if this position is before the given position, +a number greater than zero if this position is after the given position, or zero when +this and the given position are equal.

+
+
+
+ + + +isAfter(other: Position): boolean +
+

Check if this position is after other.

+
+
+ + + + + +
ParameterDescription
other: Position

A position.

+
ReturnsDescription
boolean

true if position is on a greater line +or on the same line on a greater character.

+
+
+
+ + + +isAfterOrEqual(other: Position): boolean +
+

Check if this position is after or equal to other.

+
+
+ + + + + +
ParameterDescription
other: Position

A position.

+
ReturnsDescription
boolean

true if position is on a greater line +or on the same line on a greater or equal character.

+
+
+
+ + + +isBefore(other: Position): boolean +
+

Check if this position is before other.

+
+
+ + + + + +
ParameterDescription
other: Position

A position.

+
ReturnsDescription
boolean

true if position is on a smaller line +or on the same line on a smaller character.

+
+
+
+ + + +isBeforeOrEqual(other: Position): boolean +
+

Check if this position is before or equal to other.

+
+
+ + + + + +
ParameterDescription
other: Position

A position.

+
ReturnsDescription
boolean

true if position is on a smaller line +or on the same line on a smaller or equal character.

+
+
+
+ + + +isEqual(other: Position): boolean +
+

Check if this position is equal to other.

+
+
+ + + + + +
ParameterDescription
other: Position

A position.

+
ReturnsDescription
boolean

true if the line and character of the given position are equal to +the line and character of this position.

+
+
+
+ + + +translate(lineDelta?: number, characterDelta?: number): Position +
+

Create a new position relative to this position.

+
+
+ + + + + + +
ParameterDescription
lineDelta?: number

Delta value for the line value, default is 0.

+
characterDelta?: number

Delta value for the character value, default is 0.

+
ReturnsDescription
Position

A position which line and character is the sum of the current line and +character and the corresponding deltas.

+
+
+
+ + + +translate(change: {characterDelta: number, lineDelta: number}): Position +
+

Derived a new position relative to this position.

+
+
+ + + + + +
ParameterDescription
change: {characterDelta: number, lineDelta: number}

An object that describes a delta to this position.

+
ReturnsDescription
Position

A position that reflects the given delta. Will return this position if the change +is not changing anything.

+
+
+
+ + + +with(line?: number, character?: number): Position +
+

Create a new position derived from this position.

+
+
+ + + + + + +
ParameterDescription
line?: number

Value that should be used as line value, default is the existing value

+
character?: number

Value that should be used as character value, default is the existing value

+
ReturnsDescription
Position

A position where line and character are replaced by the given values.

+
+
+
+ + + +with(change: {character: number, line: number}): Position +
+

Derived a new position from this position.

+
+
+ + + + + +
ParameterDescription
change: {character: number, line: number}

An object that describes a change to this position.

+
ReturnsDescription
Position

A position that reflects the given change. Will return this position if the change +is not changing anything.

+
+
+
+ +### ProcessExecution + + + +

The execution of a task happens as an external process +without shell interaction.

+
+ +#### Constructors + + + +new ProcessExecution(process: string, options?: ProcessExecutionOptions): ProcessExecution +
+

Creates a process execution.

+
+
+ + + + + + +
ParameterDescription
process: string

The process to start.

+
options?: ProcessExecutionOptions

Optional options for the started process.

+
ReturnsDescription
ProcessExecution
+
+
+ + + +new ProcessExecution(process: string, args: string[], options?: ProcessExecutionOptions): ProcessExecution +
+

Creates a process execution.

+
+
+ + + + + + + +
ParameterDescription
process: string

The process to start.

+
args: string[]

Arguments to be passed to the process.

+
options?: ProcessExecutionOptions

Optional options for the started process.

+
ReturnsDescription
ProcessExecution
+
+
+ +#### Properties + + + +args: string[] +
+

The arguments passed to the process. Defaults to an empty array.

+
+
+ + + +options?: ProcessExecutionOptions +
+

The process options used when the process is executed. +Defaults to undefined.

+
+
+ + + +process: string +
+

The process to be executed.

+
+
+ +### ProcessExecutionOptions + + + +

Options for a process execution

+
+ +#### Properties + + + +cwd?: string +
+

The current working directory of the executed program or shell. +If omitted the tools current workspace root is used.

+
+
+ + + +env?: +
+

The additional environment of the executed program or shell. If omitted +the parent process' environment is used. If provided it is merged with +the parent process' environment.

+
+
+ +### Progress<T> + + + +

Defines a generalized way of reporting progress updates.

+
+ +#### Methods + + + +report(value: T): void +
+

Report a progress update.

+
+
+ + + + + +
ParameterDescription
value: T

A progress item, like a message and/or an +report on how much work finished

+
ReturnsDescription
void
+
+
+ +### ProgressLocation + + + +

A location in the editor at which progress information can be shown. It depends on the +location how progress is visually represented.

+
+ +#### Enumeration members + + + +Notification +
+15 +
+ + + +SourceControl +
+1 +
+ + + +Window +
+10 +
+ +### ProgressOptions + + + +

Value-object describing where and how progress should show.

+
+ +#### Properties + + + +cancellable?: boolean +
+

Controls if a cancel button should show to allow the user to +cancel the long running operation. Note that currently only +ProgressLocation.Notification is supporting to show a cancel +button.

+
+
+ + + +location: ProgressLocation +
+

The location at which progress should show.

+
+
+ + + +title?: string +
+

A human-readable string which will be used to describe the +operation.

+
+
+ +### ProviderResult<T> + + + +

A provider result represents the values a provider, like the HoverProvider, +may return. For once this is the actual result type T, like Hover, or a thenable that resolves +to that type T. In addition, null and undefined can be returned - either directly or from a +thenable.

+

The snippets below are all valid implementations of the HoverProvider:

+ +
let a: HoverProvider = {
+    provideHover(doc, pos, token): ProviderResult<Hover> {
+        return new Hover('Hello World');
+    }
+}
+
+let b: HoverProvider = {
+    provideHover(doc, pos, token): ProviderResult<Hover> {
+        return new Promise(resolve => {
+            resolve(new Hover('Hello World'));
+         });
+    }
+}
+
+let c: HoverProvider = {
+    provideHover(doc, pos, token): ProviderResult<Hover> {
+        return; // undefined
+    }
+}
+
+
+ + + +ProviderResult: T | undefined | null | Thenable<T | undefined | null> + +### QuickDiffProvider + + + +
+ +#### Methods + + + +provideOriginalResource(uri: Uri, token: CancellationToken): ProviderResult<Uri> +
+

Provide a uri to the original resource of any given resource uri.

+
+
+ + + + + + +
ParameterDescription
uri: Uri

The uri of the resource open in a text editor.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Uri>

A thenable that resolves to uri of the matching original resource.

+
+
+
+ +### QuickInput + + + +

A light-weight user input UI that is intially not visible. After +configuring it through its properties the extension can make it +visible by calling QuickInput.show.

+

There are several reasons why this UI might have to be hidden and +the extension will be notified through QuickInput.onDidHide. +(Examples include: an explict call to QuickInput.hide, +the user pressing Esc, some other input UI opening, etc.)

+

A user pressing Enter or some other gesture implying acceptance +of the current state does not automatically hide this UI component. +It is up to the extension to decide whether to accept the user's input +and if the UI should indeed be hidden through a call to QuickInput.hide.

+

When the extension no longer needs this input UI, it should +QuickInput.dispose it to allow for freeing up +any resources associated with it.

+

See QuickPick and InputBox for concrete UIs.

+
+ +#### Events + + + +onDidHide: Event<void> +
+

An event signaling when this input UI is hidden.

+

There are several reasons why this UI might have to be hidden and +the extension will be notified through QuickInput.onDidHide. +(Examples include: an explict call to QuickInput.hide, +the user pressing Esc, some other input UI opening, etc.)

+
+
+ +#### Properties + + + +busy: boolean +
+

If the UI should show a progress indicator. Defaults to false.

+

Change this to true, e.g., while loading more data or validating +user input.

+
+
+ + + +enabled: boolean +
+

If the UI should allow for user input. Defaults to true.

+

Change this to false, e.g., while validating user input or +loading data for the next step in user input.

+
+
+ + + +ignoreFocusOut: boolean +
+

If the UI should stay open even when loosing UI focus. Defaults to false.

+
+
+ + + +step: number | undefined +
+

An optional current step count.

+
+
+ + + +title: string | undefined +
+

An optional title.

+
+
+ + + +totalSteps: number | undefined +
+

An optional total step count.

+
+
+ +#### Methods + + + +dispose(): void +
+

Dispose of this input UI and any associated resources. If it is still +visible, it is first hidden. After this call the input UI is no longer +functional and no additional methods or properties on it should be +accessed. Instead a new input UI should be created.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +hide(): void +
+

Hides this input UI. This will also fire an QuickInput.onDidHide +event.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +show(): void +
+

Makes the input UI visible in its current configuration. Any other input +UI will first fire an QuickInput.onDidHide event.

+
+
+ + + +
ReturnsDescription
void
+
+
+ +### QuickInputButton + + + +

Button for an action in a QuickPick or InputBox.

+
+ +#### Properties + + + +iconPath: Uri | {dark: Uri, light: Uri} | ThemeIcon +
+

Icon for the button.

+
+
+ + + +tooltip?: string | undefined +
+

An optional tooltip.

+
+
+ +### QuickInputButtons + + + +

Predefined buttons for QuickPick and InputBox.

+
+ +#### Static + + + +Back: QuickInputButton +
+

A back button for QuickPick and InputBox.

+

When a navigation 'back' button is needed this one should be used for consistency. +It comes with a predefined icon, tooltip and location.

+
+
+ +### QuickPick<T> + + + +

A concrete QuickInput to let the user pick an item from a +list of items of type T. The items can be filtered through a filter text field and +there is an option canSelectMany to allow for +selecting multiple items.

+

Note that in many cases the more convenient window.showQuickPick +is easier to use. window.createQuickPick should be used +when window.showQuickPick does not offer the required flexibility.

+
+ +#### Events + + + +onDidAccept: Event<void> +
+

An event signaling when the user indicated acceptance of the selected item(s).

+
+
+ + + +onDidChangeActive: Event<T[]> +
+

An event signaling when the active items have changed.

+
+
+ + + +onDidChangeSelection: Event<T[]> +
+

An event signaling when the selected items have changed.

+
+
+ + + +onDidChangeValue: Event<string> +
+

An event signaling when the value of the filter text has changed.

+
+
+ + + +onDidHide: Event<void> +
+

An event signaling when this input UI is hidden.

+

There are several reasons why this UI might have to be hidden and +the extension will be notified through QuickInput.onDidHide. +(Examples include: an explict call to QuickInput.hide, +the user pressing Esc, some other input UI opening, etc.)

+
+
+ + + +onDidTriggerButton: Event<QuickInputButton> +
+

An event signaling when a button was triggered.

+
+
+ +#### Properties + + + +activeItems: ReadonlyArray<T> +
+

Active items. This can be read and updated by the extension.

+
+
+ + + +busy: boolean +
+

If the UI should show a progress indicator. Defaults to false.

+

Change this to true, e.g., while loading more data or validating +user input.

+
+
+ + + +buttons: ReadonlyArray<QuickInputButton> +
+

Buttons for actions in the UI.

+
+
+ + + +canSelectMany: boolean +
+

If multiple items can be selected at the same time. Defaults to false.

+
+
+ + + +enabled: boolean +
+

If the UI should allow for user input. Defaults to true.

+

Change this to false, e.g., while validating user input or +loading data for the next step in user input.

+
+
+ + + +ignoreFocusOut: boolean +
+

If the UI should stay open even when loosing UI focus. Defaults to false.

+
+
+ + + +items: ReadonlyArray<T> +
+

Items to pick from.

+
+
+ + + +matchOnDescription: boolean +
+

If the filter text should also be matched against the description of the items. Defaults to false.

+
+
+ + + +matchOnDetail: boolean +
+

If the filter text should also be matched against the detail of the items. Defaults to false.

+
+
+ + + +placeholder: string | undefined +
+

Optional placeholder in the filter text.

+
+
+ + + +selectedItems: ReadonlyArray<T> +
+

Selected items. This can be read and updated by the extension.

+
+
+ + + +step: number | undefined +
+

An optional current step count.

+
+
+ + + +title: string | undefined +
+

An optional title.

+
+
+ + + +totalSteps: number | undefined +
+

An optional total step count.

+
+
+ + + +value: string +
+

Current value of the filter text.

+
+
+ +#### Methods + + + +dispose(): void +
+

Dispose of this input UI and any associated resources. If it is still +visible, it is first hidden. After this call the input UI is no longer +functional and no additional methods or properties on it should be +accessed. Instead a new input UI should be created.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +hide(): void +
+

Hides this input UI. This will also fire an QuickInput.onDidHide +event.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +show(): void +
+

Makes the input UI visible in its current configuration. Any other input +UI will first fire an QuickInput.onDidHide event.

+
+
+ + + +
ReturnsDescription
void
+
+
+ +### QuickPickItem + + + +

Represents an item that can be selected from +a list of items.

+
+ +#### Properties + + + +alwaysShow?: boolean +
+

Always show this item.

+
+
+ + + +description?: string +
+

A human readable string which is rendered less prominent.

+
+
+ + + +detail?: string +
+

A human readable string which is rendered less prominent.

+
+
+ + + +label: string +
+

A human readable string which is rendered prominent.

+
+
+ + + +picked?: boolean +
+

Optional flag indicating if this item is picked initially. +(Only honored when the picker allows multiple selections.)

+ +
+
+ +### QuickPickOptions + + + +

Options to configure the behavior of the quick pick UI.

+
+ +#### Events + + + +onDidSelectItem(item: QuickPickItem | string): any +
+

An optional function that is invoked whenever an item is selected.

+
+
+ + + + + +
ParameterDescription
item: QuickPickItem | string
ReturnsDescription
any
+
+
+ +#### Properties + + + +canPickMany?: boolean +
+

An optional flag to make the picker accept multiple selections, if true the result is an array of picks.

+
+
+ + + +ignoreFocusOut?: boolean +
+

Set to true to keep the picker open when focus moves to another part of the editor or to another window.

+
+
+ + + +matchOnDescription?: boolean +
+

An optional flag to include the description when filtering the picks.

+
+
+ + + +matchOnDetail?: boolean +
+

An optional flag to include the detail when filtering the picks.

+
+
+ + + +placeHolder?: string +
+

An optional string to show as place holder in the input box to guide the user what to pick on.

+
+
+ +### Range + + + +

A range represents an ordered pair of two positions. +It is guaranteed that start.isBeforeOrEqual(end)

+

Range objects are immutable. Use the with, +intersection, or union methods +to derive new ranges from an existing range.

+
+ +#### Constructors + + + +new Range(start: Position, end: Position): Range +
+

Create a new range from two positions. If start is not +before or equal to end, the values will be swapped.

+
+
+ + + + + + +
ParameterDescription
start: Position

A position.

+
end: Position

A position.

+
ReturnsDescription
Range
+
+
+ + + +new Range(startLine: number, startCharacter: number, endLine: number, endCharacter: number): Range +
+

Create a new range from number coordinates. It is a shorter equivalent of +using new Range(new Position(startLine, startCharacter), new Position(endLine, endCharacter))

+
+
+ + + + + + + + +
ParameterDescription
startLine: number

A zero-based line value.

+
startCharacter: number

A zero-based character value.

+
endLine: number

A zero-based line value.

+
endCharacter: number

A zero-based character value.

+
ReturnsDescription
Range
+
+
+ +#### Properties + + + +end: Position +
+

The end position. It is after or equal to start.

+
+
+ + + +isEmpty: boolean +
+

true if start and end are equal.

+
+
+ + + +isSingleLine: boolean +
+

true if start.line and end.line are equal.

+
+
+ + + +start: Position +
+

The start position. It is before or equal to end.

+
+
+ +#### Methods + + + +contains(positionOrRange: Position | Range): boolean +
+

Check if a position or a range is contained in this range.

+
+
+ + + + + +
ParameterDescription
positionOrRange: Position | Range

A position or a range.

+
ReturnsDescription
boolean

true if the position or range is inside or equal +to this range.

+
+
+
+ + + +intersection(range: Range): Range | undefined +
+

Intersect range with this range and returns a new range or undefined +if the ranges have no overlap.

+
+
+ + + + + +
ParameterDescription
range: Range

A range.

+
ReturnsDescription
Range | undefined

A range of the greater start and smaller end positions. Will +return undefined when there is no overlap.

+
+
+
+ + + +isEqual(other: Range): boolean +
+

Check if other equals this range.

+
+
+ + + + + +
ParameterDescription
other: Range

A range.

+
ReturnsDescription
boolean

true when start and end are equal to +start and end of this range.

+
+
+
+ + + +union(other: Range): Range +
+

Compute the union of other with this range.

+
+
+ + + + + +
ParameterDescription
other: Range

A range.

+
ReturnsDescription
Range

A range of smaller start position and the greater end position.

+
+
+
+ + + +with(start?: Position, end?: Position): Range +
+

Derived a new range from this range.

+
+
+ + + + + + +
ParameterDescription
start?: Position

A position that should be used as start. The default value is the current start.

+
end?: Position

A position that should be used as end. The default value is the current end.

+
ReturnsDescription
Range

A range derived from this range with the given start and end position. +If start and end are not different this range will be returned.

+
+
+
+ + + +with(change: {end: Position, start: Position}): Range +
+

Derived a new range from this range.

+
+
+ + + + + +
ParameterDescription
change: {end: Position, start: Position}

An object that describes a change to this range.

+
ReturnsDescription
Range

A range that reflects the given change. Will return this range if the change +is not changing anything.

+
+
+
+ +### ReferenceContext + + + +

Value-object that contains additional information when +requesting references.

+
+ +#### Properties + + + +includeDeclaration: boolean +
+

Include the declaration of the current symbol.

+
+
+ +### ReferenceProvider + + + +

The reference provider interface defines the contract between extensions and +the find references-feature.

+
+ +#### Methods + + + +provideReferences(document: TextDocument, position: Position, context: ReferenceContext, token: CancellationToken): ProviderResult<Location[]> +
+

Provide a set of project-wide references for the given position and document.

+
+
+ + + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
context: ReferenceContext
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Location[]>

An array of locations or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined, null, or an empty array.

+
+
+
+ +### RelativePattern + + + +

A relative pattern is a helper to construct glob patterns that are matched +relatively to a base path. The base path can either be an absolute file path +or a workspace folder.

+
+ +#### Constructors + + + +new RelativePattern(base: WorkspaceFolder | string, pattern: string): RelativePattern +
+

Creates a new relative pattern object with a base path and pattern to match. This pattern +will be matched on file paths relative to the base path.

+
+
+ + + + + + +
ParameterDescription
base: WorkspaceFolder | string

A base file path to which this pattern will be matched against relatively.

+
pattern: string

A file glob pattern like *.{ts,js} that will be matched on file paths +relative to the base path.

+
ReturnsDescription
RelativePattern
+
+
+ +#### Properties + + + +base: string +
+

A base file path to which this pattern will be matched against relatively.

+
+
+ + + +pattern: string +
+

A file glob pattern like *.{ts,js} that will be matched on file paths +relative to the base path.

+

Example: Given a base of /home/work/folder and a file path of /home/work/folder/index.js, +the file glob pattern will match on index.js.

+
+
+ +### RenameProvider + + + +

The rename provider interface defines the contract between extensions and +the rename-feature.

+
+ +#### Methods + + + +prepareRename(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Range | {placeholder: string, range: Range}> +
+

Optional function for resolving and validating a position before running rename. The result can +be a range or a range and a placeholder text. The placeholder text should be the identifier of the symbol +which is being renamed - when omitted the text in the returned range is used.

+
+
+ + + + + + + +
ParameterDescription
document: TextDocument

The document in which rename will be invoked.

+
position: Position

The position at which rename will be invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Range | {placeholder: string, range: Range}>

The range or range and placeholder text of the identifier that is to be renamed. The lack of a result can signaled by returning undefined or null.

+
+
+
+ + + +provideRenameEdits(document: TextDocument, position: Position, newName: string, token: CancellationToken): ProviderResult<WorkspaceEdit> +
+

Provide an edit that describes changes that have to be made to one +or many resources to rename a symbol to a different name.

+
+
+ + + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
newName: string

The new name of the symbol. If the given name is not valid, the provider must return a rejected promise.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<WorkspaceEdit>

A workspace edit or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined or null.

+
+
+
+ +### RunOptions + + + +

Run options for a task.

+
+ +#### Properties + + + +reevaluateOnRerun?: boolean +
+

Controls whether task variables are re-evaluated on rerun.

+
+
+ +### SaveDialogOptions + + + +

Options to configure the behaviour of a file save dialog.

+
+ +#### Properties + + + +defaultUri?: Uri +
+

The resource the dialog shows when opened.

+
+
+ + + +filters?: +
+

A set of file filters that are used by the dialog. Each entry is a human readable label, +like "TypeScript", and an array of extensions, e.g.

+ +
{
+    'Images': ['png', 'jpg']
+    'TypeScript': ['ts', 'tsx']
+}
+
+
+
+ + + +saveLabel?: string +
+

A human-readable string for the save button.

+
+
+ +### Selection + + + +

Represents a text selection in an editor.

+
+ +#### Constructors + + + +new Selection(anchor: Position, active: Position): Selection +
+

Create a selection from two positions.

+
+
+ + + + + + +
ParameterDescription
anchor: Position

A position.

+
active: Position

A position.

+
ReturnsDescription
Selection
+
+
+ + + +new Selection(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number): Selection +
+

Create a selection from four coordinates.

+
+
+ + + + + + + + +
ParameterDescription
anchorLine: number

A zero-based line value.

+
anchorCharacter: number

A zero-based character value.

+
activeLine: number

A zero-based line value.

+
activeCharacter: number

A zero-based character value.

+
ReturnsDescription
Selection
+
+
+ +#### Properties + + + +active: Position +
+

The position of the cursor. +This position might be before or after anchor.

+
+
+ + + +anchor: Position +
+

The position at which the selection starts. +This position might be before or after active.

+
+
+ + + +end: Position +
+

The end position. It is after or equal to start.

+
+
+ + + +isEmpty: boolean +
+

true if start and end are equal.

+
+
+ + + +isReversed: boolean +
+

A selection is reversed if active.isBefore(anchor).

+
+
+ + + +isSingleLine: boolean +
+

true if start.line and end.line are equal.

+
+
+ + + +start: Position +
+

The start position. It is before or equal to end.

+
+
+ +#### Methods + + + +contains(positionOrRange: Position | Range): boolean +
+

Check if a position or a range is contained in this range.

+
+
+ + + + + +
ParameterDescription
positionOrRange: Position | Range

A position or a range.

+
ReturnsDescription
boolean

true if the position or range is inside or equal +to this range.

+
+
+
+ + + +intersection(range: Range): Range | undefined +
+

Intersect range with this range and returns a new range or undefined +if the ranges have no overlap.

+
+
+ + + + + +
ParameterDescription
range: Range

A range.

+
ReturnsDescription
Range | undefined

A range of the greater start and smaller end positions. Will +return undefined when there is no overlap.

+
+
+
+ + + +isEqual(other: Range): boolean +
+

Check if other equals this range.

+
+
+ + + + + +
ParameterDescription
other: Range

A range.

+
ReturnsDescription
boolean

true when start and end are equal to +start and end of this range.

+
+
+
+ + + +union(other: Range): Range +
+

Compute the union of other with this range.

+
+
+ + + + + +
ParameterDescription
other: Range

A range.

+
ReturnsDescription
Range

A range of smaller start position and the greater end position.

+
+
+
+ + + +with(start?: Position, end?: Position): Range +
+

Derived a new range from this range.

+
+
+ + + + + + +
ParameterDescription
start?: Position

A position that should be used as start. The default value is the current start.

+
end?: Position

A position that should be used as end. The default value is the current end.

+
ReturnsDescription
Range

A range derived from this range with the given start and end position. +If start and end are not different this range will be returned.

+
+
+
+ + + +with(change: {end: Position, start: Position}): Range +
+

Derived a new range from this range.

+
+
+ + + + + +
ParameterDescription
change: {end: Position, start: Position}

An object that describes a change to this range.

+
ReturnsDescription
Range

A range that reflects the given change. Will return this range if the change +is not changing anything.

+
+
+
+ +### ShellExecution + + + +
+ +#### Constructors + + + +new ShellExecution(commandLine: string, options?: ShellExecutionOptions): ShellExecution +
+

Creates a shell execution with a full command line.

+
+
+ + + + + + +
ParameterDescription
commandLine: string

The command line to execute.

+
options?: ShellExecutionOptions

Optional options for the started the shell.

+
ReturnsDescription
ShellExecution
+
+
+ + + +new ShellExecution(command: string | ShellQuotedString, args: string | ShellQuotedString[], options?: ShellExecutionOptions): ShellExecution +
+

Creates a shell execution with a command and arguments. For the real execution VS Code will +construct a command line from the command and the arguments. This is subject to interpretation +especially when it comes to quoting. If full control over the command line is needed please +use the constructor that creates a ShellExecution with the full command line.

+
+
+ + + + + + + +
ParameterDescription
command: string | ShellQuotedString

The command to execute.

+
args: string | ShellQuotedString[]

The command arguments.

+
options?: ShellExecutionOptions

Optional options for the started the shell.

+
ReturnsDescription
ShellExecution
+
+
+ +#### Properties + + + +args: string | ShellQuotedString[] +
+

The shell args. Is undefined if created with a full command line.

+
+
+ + + +command: string | ShellQuotedString +
+

The shell command. Is undefined if created with a full command line.

+
+
+ + + +commandLine: string +
+

The shell command line. Is undefined if created with a command and arguments.

+
+
+ + + +options?: ShellExecutionOptions +
+

The shell options used when the command line is executed in a shell. +Defaults to undefined.

+
+
+ +### ShellExecutionOptions + + + +

Options for a shell execution

+
+ +#### Properties + + + +cwd?: string +
+

The current working directory of the executed shell. +If omitted the tools current workspace root is used.

+
+
+ + + +env?: +
+

The additional environment of the executed shell. If omitted +the parent process' environment is used. If provided it is merged with +the parent process' environment.

+
+
+ + + +executable?: string +
+

The shell executable.

+
+
+ + + +shellArgs?: string[] +
+

The arguments to be passed to the shell executable used to run the task. Most shells +require special arguments to execute a command. For example bash requires the -c +argument to execute a command, PowerShell requires -Command and cmd requires both +/d and /c.

+
+
+ + + +shellQuoting?: ShellQuotingOptions +
+

The shell quotes supported by this shell.

+
+
+ +### ShellQuotedString + + + +

A string that will be quoted depending on the used shell.

+
+ +#### Properties + + + +quoting: ShellQuoting +
+

The quoting style to use.

+
+
+ + + +value: string +
+

The actual string value.

+
+
+ +### ShellQuoting + + + +

Defines how an argument should be quoted if it contains +spaces or unsupported characters.

+
+ +#### Enumeration members + + + +Escape +
+1 +
+ + + +Strong +
+2 +
+ + + +Weak +
+3 +
+ +### ShellQuotingOptions + + + +

The shell quoting options.

+
+ +#### Properties + + + +escape?: string | {charsToEscape: string, escapeChar: string} +
+

The character used to do character escaping. If a string is provided only spaces +are escaped. If a { escapeChar, charsToEscape } literal is provide all characters +in charsToEscape are escaped using the escapeChar.

+
+
+ + + +strong?: string +
+

The character used for strong quoting. The string's length must be 1.

+
+
+ + + +weak?: string +
+

The character used for weak quoting. The string's length must be 1.

+
+
+ +### SignatureHelp + + + +

Signature help represents the signature of something +callable. There can be multiple signatures but only one +active and only one active parameter.

+
+ +#### Properties + + + +activeParameter: number +
+

The active parameter of the active signature.

+
+
+ + + +activeSignature: number +
+

The active signature.

+
+
+ + + +signatures: SignatureInformation[] +
+

One or more signatures.

+
+
+ +### SignatureHelpContext + + + +

Additional information about the context in which a +SignatureHelpProvider was triggered.

+
+ +#### Properties + + + +isRetrigger: boolean +
+

true if signature help was already showing when it was triggered.

+

Retriggers occur when the signature help is already active and can be caused by actions such as +typing a trigger character, a cursor move, or document content changes.

+
+
+ + + +triggerCharacter?: string +
+

Character that caused signature help to be triggered.

+

This is undefined when signature help is not triggered by typing, such as when manually invoking +signature help or when moving the cursor.

+
+
+ + + +triggerKind: SignatureHelpTriggerKind +
+

Action that caused signature help to be triggered.

+
+
+ +### SignatureHelpProvider + + + +

The signature help provider interface defines the contract between extensions and +the parameter hints-feature.

+
+ +#### Methods + + + +provideSignatureHelp(document: TextDocument, position: Position, token: CancellationToken, context: SignatureHelpContext): ProviderResult<SignatureHelp> +
+

Provide help for the signature at the given position and document.

+
+
+ + + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
context: SignatureHelpContext

Information about how signature help was triggered.

+
ReturnsDescription
ProviderResult<SignatureHelp>

Signature help or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined or null.

+
+
+
+ +### SignatureHelpProviderMetadata + + + +

Metadata about a registered SignatureHelpProvider.

+
+ +#### Properties + + + +retriggerCharacters: ReadonlyArray<string> +
+

List of characters that re-trigger signature help.

+

These trigger characters are only active when signature help is alread showing. All trigger characters +are also counted as re-trigger characters.

+
+
+ + + +triggerCharacters: ReadonlyArray<string> +
+

List of characters that trigger signature help.

+
+
+ +### SignatureHelpTriggerKind + + + +

How a SignatureHelpProvider was triggered.

+
+ +#### Enumeration members + + + +ContentChange +
+3 +
+ + + +Invoke +
+1 +
+ + + +TriggerCharacter +
+2 +
+ +### SignatureInformation + + + +

Represents the signature of something callable. A signature +can have a label, like a function-name, a doc-comment, and +a set of parameters.

+
+ +#### Constructors + + + +new SignatureInformation(label: string, documentation?: string | MarkdownString): SignatureInformation +
+

Creates a new signature information object.

+
+
+ + + + + + +
ParameterDescription
label: string

A label string.

+
documentation?: string | MarkdownString

A doc string.

+
ReturnsDescription
SignatureInformation
+
+
+ +#### Properties + + + +documentation?: string | MarkdownString +
+

The human-readable doc-comment of this signature. Will be shown +in the UI but can be omitted.

+
+
+ + + +label: string +
+

The label of this signature. Will be shown in +the UI.

+
+
+ + + +parameters: ParameterInformation[] +
+

The parameters of this signature.

+
+
+ +### SnippetString + + + +

A snippet string is a template which allows to insert text +and to control the editor cursor when insertion happens.

+

A snippet can define tab stops and placeholders with $1, $2 +and ${3:foo}. $0 defines the final tab stop, it defaults to +the end of the snippet. Variables are defined with $name and +${name:default value}. The full snippet syntax is documented +here.

+
+ +#### Constructors + + + +new SnippetString(value?: string): SnippetString +
+
+
+ + + + + +
ParameterDescription
value?: string
ReturnsDescription
SnippetString
+
+
+ +#### Properties + + + +value: string +
+

The snippet string.

+
+
+ +#### Methods + + + +appendPlaceholder(value: string | (snippet: SnippetString) => any, number?: number): SnippetString +
+

Builder-function that appends a placeholder (${1:value}) to +the value of this snippet string.

+
+
+ + + + + + +
ParameterDescription
value: string | (snippet: SnippetString) => any

The value of this placeholder - either a string or a function +with which a nested snippet can be created.

+
number?: number

The number of this tabstop, defaults to an auto-increment +value starting at 1.

+
ReturnsDescription
SnippetString

This snippet string.

+
+
+
+ + + +appendTabstop(number?: number): SnippetString +
+

Builder-function that appends a tabstop ($1, $2 etc) to +the value of this snippet string.

+
+
+ + + + + +
ParameterDescription
number?: number

The number of this tabstop, defaults to an auto-increment +value starting at 1.

+
ReturnsDescription
SnippetString

This snippet string.

+
+
+
+ + + +appendText(string: string): SnippetString +
+

Builder-function that appends the given string to +the value of this snippet string.

+
+
+ + + + + +
ParameterDescription
string: string

A value to append 'as given'. The string will be escaped.

+
ReturnsDescription
SnippetString

This snippet string.

+
+
+
+ + + +appendVariable(name: string, defaultValue: string | (snippet: SnippetString) => any): SnippetString +
+

Builder-function that appends a variable (${VAR}) to +the value of this snippet string.

+
+
+ + + + + + +
ParameterDescription
name: string

The name of the variable - excluding the $.

+
defaultValue: string | (snippet: SnippetString) => any

The default value which is used when the variable name cannot +be resolved - either a string or a function with which a nested snippet can be created.

+
ReturnsDescription
SnippetString

This snippet string.

+
+
+
+ +### SourceBreakpoint + + + +

A breakpoint specified by a source location.

+
+ +#### Constructors + + + +new SourceBreakpoint(location: Location, enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): SourceBreakpoint +
+

Create a new breakpoint for a source location.

+
+
+ + + + + + + + + +
ParameterDescription
location: Location
enabled?: boolean
condition?: string
hitCondition?: string
logMessage?: string
ReturnsDescription
SourceBreakpoint
+
+
+ +#### Properties + + + +condition?: string +
+

An optional expression for conditional breakpoints.

+
+
+ + + +enabled: boolean +
+

Is breakpoint enabled.

+
+
+ + + +hitCondition?: string +
+

An optional expression that controls how many hits of the breakpoint are ignored.

+
+
+ + + +id: string +
+

The unique ID of the breakpoint.

+
+
+ + + +location: Location +
+

The source and line position of this breakpoint.

+
+
+ + + +logMessage?: string +
+

An optional message that gets logged when this breakpoint is hit. Embedded expressions within {} are interpolated by the debug adapter.

+
+
+ +### SourceControl + + + +

An source control is able to provide resource states +to the editor and interact with the editor in several source control related ways.

+
+ +#### Properties + + + +acceptInputCommand?: Command +
+

Optional accept input command.

+

This command will be invoked when the user accepts the value +in the Source Control input.

+
+
+ + + +commitTemplate?: string +
+

Optional commit template string.

+

The Source Control viewlet will populate the Source Control +input with this value when appropriate.

+
+
+ + + +count?: number +
+

The UI-visible count of resource states of +this source control.

+

Equals to the total number of resource state +of this source control, if undefined.

+
+
+ + + +id: string +
+

The id of this source control.

+
+
+ + + +inputBox: SourceControlInputBox +
+

The input box for this source control.

+
+
+ + + +label: string +
+

The human-readable label of this source control.

+
+
+ + + +quickDiffProvider?: QuickDiffProvider +
+

An optional quick diff provider.

+
+
+ + + +rootUri: Uri | undefined +
+

The (optional) Uri of the root of this source control.

+
+
+ + + +statusBarCommands?: Command[] +
+

Optional status bar commands.

+

These commands will be displayed in the editor's status bar.

+
+
+ +#### Methods + + + +createResourceGroup(id: string, label: string): SourceControlResourceGroup +
+

Create a new resource group.

+
+
+ + + + + + +
ParameterDescription
id: string
label: string
ReturnsDescription
SourceControlResourceGroup
+
+
+ + + +dispose(): void +
+

Dispose this source control.

+
+
+ + + +
ReturnsDescription
void
+
+
+ +### SourceControlInputBox + + + +

Represents the input box in the Source Control viewlet.

+
+ +#### Properties + + + +placeholder: string +
+

A string to show as place holder in the input box to guide the user.

+
+
+ + + +value: string +
+

Setter and getter for the contents of the input box.

+
+
+ +### SourceControlResourceDecorations + + + +

The decorations for a source control resource state. +Can be independently specified for light and dark themes.

+
+ +#### Properties + + + +dark?: SourceControlResourceThemableDecorations +
+

The dark theme decorations.

+
+
+ + + +faded?: boolean +
+

Whether the source control resource state should +be faded in the UI.

+
+
+ + + +iconPath?: string | Uri +
+

The icon path for a specific +source control resource state.

+
+
+ + + +light?: SourceControlResourceThemableDecorations +
+

The light theme decorations.

+
+
+ + + +strikeThrough?: boolean +
+

Whether the source control resource state should +be striked-through in the UI.

+
+
+ + + +tooltip?: string +
+

The title for a specific +source control resource state.

+
+
+ +### SourceControlResourceGroup + + + +

A source control resource group is a collection of +source control resource states.

+
+ +#### Properties + + + +hideWhenEmpty?: boolean +
+

Whether this source control resource group is hidden when it contains +no source control resource states.

+
+
+ + + +id: string +
+

The id of this source control resource group.

+
+
+ + + +label: string +
+

The label of this source control resource group.

+
+
+ + + +resourceStates: SourceControlResourceState[] +
+

This group's collection of +source control resource states.

+
+
+ +#### Methods + + + +dispose(): void +
+

Dispose this source control resource group.

+
+
+ + + +
ReturnsDescription
void
+
+
+ +### SourceControlResourceState + + + +

An source control resource state represents the state of an underlying workspace +resource within a certain source control group.

+
+ +#### Properties + + + +command?: Command +
+

The command which should be run when the resource +state is open in the Source Control viewlet.

+
+
+ + + +decorations?: SourceControlResourceDecorations +
+

The decorations for this source control +resource state.

+
+
+ + + +resourceUri: Uri +
+

The uri of the underlying resource inside the workspace.

+
+
+ +### SourceControlResourceThemableDecorations + + + +

The theme-aware decorations for a +source control resource state.

+
+ +#### Properties + + + +iconPath?: string | Uri +
+

The icon path for a specific +source control resource state.

+
+
+ +### StatusBarAlignment + + + +

Represents the alignment of status bar items.

+
+ +#### Enumeration members + + + +Left +
+1 +
+ + + +Right +
+2 +
+ +### StatusBarItem + + + +

A status bar item is a status bar contribution that can +show text and icons and run a command on click.

+
+ +#### Properties + + + +alignment: StatusBarAlignment +
+

The alignment of this item.

+
+
+ + + +color: string | ThemeColor | undefined +
+

The foreground color for this entry.

+
+
+ + + +command: string | undefined +
+

The identifier of a command to run on click. The command must be +known.

+
+
+ + + +priority: number +
+

The priority of this item. Higher value means the item should +be shown more to the left.

+
+
+ + + +text: string +
+

The text to show for the entry. You can embed icons in the text by leveraging the syntax:

+

My text $(icon-name) contains icons like $(icon-name) this one.

+

Where the icon-name is taken from the octicon icon set, e.g. +light-bulb, thumbsup, zap etc.

+
+
+ + + +tooltip: string | undefined +
+

The tooltip text when you hover over this entry.

+
+
+ +#### Methods + + + +dispose(): void +
+

Dispose and free associated resources. Call +hide.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +hide(): void +
+

Hide the entry in the status bar.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +show(): void +
+

Shows the entry in the status bar.

+
+
+ + + +
ReturnsDescription
void
+
+
+ +### SymbolInformation + + + +

Represents information about programming constructs like variables, classes, +interfaces etc.

+
+ +#### Constructors + + + +new SymbolInformation(name: string, kind: SymbolKind, containerName: string, location: Location): SymbolInformation +
+

Creates a new symbol information object.

+
+
+ + + + + + + + +
ParameterDescription
name: string

The name of the symbol.

+
kind: SymbolKind

The kind of the symbol.

+
containerName: string

The name of the symbol containing the symbol.

+
location: Location

The location of the symbol.

+
ReturnsDescription
SymbolInformation
+
+
+ + + +new SymbolInformation(name: string, kind: SymbolKind, range: Range, uri?: Uri, containerName?: string): SymbolInformation +
+

Creates a new symbol information object.

+
    +
  • deprecated - Please use the constructor taking a location object.
    • +
+
+
+ + + + + + + + + +
ParameterDescription
name: string

The name of the symbol.

+
kind: SymbolKind

The kind of the symbol.

+
range: Range

The range of the location of the symbol.

+
uri?: Uri

The resource of the location of symbol, defaults to the current document.

+
containerName?: string

The name of the symbol containing the symbol.

+
ReturnsDescription
SymbolInformation
+
+
+ +#### Properties + + + +containerName: string +
+

The name of the symbol containing this symbol.

+
+
+ + + +kind: SymbolKind +
+

The kind of this symbol.

+
+
+ + + +location: Location +
+

The location of this symbol.

+
+
+ + + +name: string +
+

The name of this symbol.

+
+
+ +### SymbolKind + + + +

A symbol kind.

+
+ +#### Enumeration members + + + +Array +
+17 +
+ + + +Boolean +
+16 +
+ + + +Class +
+4 +
+ + + +Constant +
+13 +
+ + + +Constructor +
+8 +
+ + + +Enum +
+9 +
+ + + +EnumMember +
+21 +
+ + + +Event +
+23 +
+ + + +Field +
+7 +
+ + + +File +
+0 +
+ + + +Function +
+11 +
+ + + +Interface +
+10 +
+ + + +Key +
+19 +
+ + + +Method +
+5 +
+ + + +Module +
+1 +
+ + + +Namespace +
+2 +
+ + + +Null +
+20 +
+ + + +Number +
+15 +
+ + + +Object +
+18 +
+ + + +Operator +
+24 +
+ + + +Package +
+3 +
+ + + +Property +
+6 +
+ + + +String +
+14 +
+ + + +Struct +
+22 +
+ + + +TypeParameter +
+25 +
+ + + +Variable +
+12 +
+ +### Task + + + +

A task to execute

+
+ +#### Constructors + + + +new Task(taskDefinition: TaskDefinition, scope: WorkspaceFolder | Global | Workspace, name: string, source: string, execution?: ProcessExecution | ShellExecution, problemMatchers?: string | string[]): Task +
+

Creates a new task.

+
+
+ + + + + + + + + + +
ParameterDescription
taskDefinition: TaskDefinition
scope: WorkspaceFolder | Global | Workspace

Specifies the task's scope. It is either a global or a workspace task or a task for a specific workspace folder.

+
name: string

The task's name. Is presented in the user interface.

+
source: string

The task's source (e.g. 'gulp', 'npm', ...). Is presented in the user interface.

+
execution?: ProcessExecution | ShellExecution

The process or shell execution.

+
problemMatchers?: string | string[]

the names of problem matchers to use, like '$tsc' + or '$eslint'. Problem matchers can be contributed by an extension using + the problemMatchers extension point.

+
ReturnsDescription
Task
+
+
+ + + +new Task(taskDefinition: TaskDefinition, name: string, source: string, execution?: ProcessExecution | ShellExecution, problemMatchers?: string | string[]): Task +
+

Creates a new task.

+
    +
  • deprecated - Use the new constructors that allow specifying a scope for the task.
    • +
+
+
+ + + + + + + + + +
ParameterDescription
taskDefinition: TaskDefinition
name: string

The task's name. Is presented in the user interface.

+
source: string

The task's source (e.g. 'gulp', 'npm', ...). Is presented in the user interface.

+
execution?: ProcessExecution | ShellExecution

The process or shell execution.

+
problemMatchers?: string | string[]

the names of problem matchers to use, like '$tsc' + or '$eslint'. Problem matchers can be contributed by an extension using + the problemMatchers extension point.

+
ReturnsDescription
Task
+
+
+ +#### Properties + + + +definition: TaskDefinition +
+

The task's definition.

+
+
+ + + +execution?: ProcessExecution | ShellExecution +
+

The task's execution engine

+
+
+ + + +group?: TaskGroup +
+

The task group this tasks belongs to. See TaskGroup +for a predefined set of available groups. +Defaults to undefined meaning that the task doesn't +belong to any special group.

+
+
+ + + +isBackground: boolean +
+

Whether the task is a background task or not.

+
+
+ + + +name: string +
+

The task's name

+
+
+ + + +presentationOptions: TaskPresentationOptions +
+

The presentation options. Defaults to an empty literal.

+
+
+ + + +problemMatchers: string[] +
+

The problem matchers attached to the task. Defaults to an empty +array.

+
+
+ + + +runOptions: RunOptions +
+

Run options for the task

+
+
+ + + +scope?: Global | Workspace | WorkspaceFolder +
+

The task's scope.

+
+
+ + + +source: string +
+

A human-readable string describing the source of this +shell task, e.g. 'gulp' or 'npm'.

+
+
+ +### TaskDefinition + + + +

A structure that defines a task kind in the system. +The value must be JSON-stringifyable.

+
+ +#### Properties + + + +type: string +
+

The task definition describing the task provided by an extension. +Usually a task provider defines more properties to identify +a task. They need to be defined in the package.json of the +extension under the 'taskDefinitions' extension point. The npm +task definition for example looks like this

+ +
interface NpmTaskDefinition extends TaskDefinition {
+    script: string;
+}
+
+

Note that type identifier starting with a '$' are reserved for internal +usages and shouldn't be used by extensions.

+
+
+ +### TaskEndEvent + + + +

An event signaling the end of an executed task.

+

This interface is not intended to be implemented.

+
+ +#### Properties + + + +execution: TaskExecution +
+

The task item representing the task that finished.

+
+
+ +### TaskExecution + + + +

An object representing an executed Task. It can be used +to terminate a task.

+

This interface is not intended to be implemented.

+
+ +#### Properties + + + +task: Task +
+

The task that got started.

+
+
+ +#### Methods + + + +terminate(): void +
+

Terminates the task execution.

+
+
+ + + +
ReturnsDescription
void
+
+
+ +### TaskFilter + + + +
+ +#### Properties + + + +type?: string +
+

The task type to return;

+
+
+ + + +version?: string +
+

The task version as used in the tasks.json file. +The string support the package.json semver notation.

+
+
+ +### TaskGroup + + + +

A grouping for tasks. The editor by default supports the +'Clean', 'Build', 'RebuildAll' and 'Test' group.

+
+ +#### Static + + + +Build: TaskGroup +
+

The build task group;

+
+
+ + + +Clean: TaskGroup +
+

The clean task group;

+
+
+ + + +Rebuild: TaskGroup +
+

The rebuild all task group;

+
+
+ + + +Test: TaskGroup +
+

The test all task group;

+
+
+ +#### Constructors + + + +new TaskGroup(id: string, label: string): TaskGroup +
+
+
+ + + + + + +
ParameterDescription
id: string
label: string
ReturnsDescription
TaskGroup
+
+
+ +### TaskPanelKind + + + +

Controls how the task channel is used between tasks

+
+ +#### Enumeration members + + + +Dedicated +
+2 +
+ + + +New +
+3 +
+ + + +Shared +
+1 +
+ +### TaskPresentationOptions + + + +

Controls how the task is presented in the UI.

+
+ +#### Properties + + + +clear?: boolean +
+

Controls whether the terminal is cleared before executing the task.

+
+
+ + + +echo?: boolean +
+

Controls whether the command associated with the task is echoed +in the user interface.

+
+
+ + + +focus?: boolean +
+

Controls whether the panel showing the task output is taking focus.

+
+
+ + + +panel?: TaskPanelKind +
+

Controls if the task panel is used for this task only (dedicated), +shared between tasks (shared) or if a new panel is created on +every task execution (new). Defaults to TaskInstanceKind.Shared

+
+
+ + + +reveal?: TaskRevealKind +
+

Controls whether the task output is reveal in the user interface. +Defaults to RevealKind.Always.

+
+
+ + + +showReuseMessage?: boolean +
+

Controls whether to show the "Terminal will be reused by tasks, press any key to close it" message.

+
+
+ +### TaskProcessEndEvent + + + +

An event signaling the end of a process execution +triggered through a task

+
+ +#### Properties + + + +execution: TaskExecution +
+

The task execution for which the process got started.

+
+
+ + + +exitCode: number +
+

The process's exit code.

+
+
+ +### TaskProcessStartEvent + + + +

An event signaling the start of a process execution +triggered through a task

+
+ +#### Properties + + + +execution: TaskExecution +
+

The task execution for which the process got started.

+
+
+ + + +processId: number +
+

The underlying process id.

+
+
+ +### TaskProvider + + + +

A task provider allows to add tasks to the task service. +A task provider is registered via #tasks.registerTaskProvider.

+
+ +#### Methods + + + +provideTasks(token?: CancellationToken): ProviderResult<Task[]> +
+

Provides tasks.

+
+
+ + + + + +
ParameterDescription
token?: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Task[]>

an array of tasks

+
+
+
+ + + +resolveTask(task: Task, token?: CancellationToken): ProviderResult<Task> +
+

Resolves a task that has no execution set. Tasks are +often created from information found in the tasks.json-file. Such tasks miss +the information on how to execute them and a task provider must fill in +the missing information in the resolveTask-method. This method will not be +called for tasks returned from the above provideTasks method since those +tasks are always fully resolved. A valid default implementation for the +resolveTask method is to return undefined.

+
+
+ + + + + + +
ParameterDescription
task: Task

The task to resolve.

+
token?: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Task>

The resolved task

+
+
+
+ +### TaskRevealKind + + + +

Controls the behaviour of the terminal's visibility.

+
+ +#### Enumeration members + + + +Always +
+1 +
+ + + +Never +
+3 +
+ + + +Silent +
+2 +
+ +### TaskScope + + + +

The scope of a task.

+
+ +#### Enumeration members + + + +Global +
+1 +
+ + + +Workspace +
+2 +
+ +### TaskStartEvent + + + +

An event signaling the start of a task execution.

+

This interface is not intended to be implemented.

+
+ +#### Properties + + + +execution: TaskExecution +
+

The task item representing the task that got started.

+
+
+ +### Terminal + + + +

An individual terminal instance within the integrated terminal.

+
+ +#### Properties + + + +name: string +
+

The name of the terminal.

+
+
+ + + +processId: Thenable<number> +
+

The process ID of the shell process.

+
+
+ +#### Methods + + + +dispose(): void +
+

Dispose and free associated resources.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +hide(): void +
+

Hide the terminal panel if this terminal is currently showing.

+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +sendText(text: string, addNewLine?: boolean): void +
+

Send text to the terminal. The text is written to the stdin of the underlying pty process +(shell) of the terminal.

+
+
+ + + + + + +
ParameterDescription
text: string

The text to send.

+
addNewLine?: boolean

Whether to add a new line to the text being sent, this is normally +required to run a command in the terminal. The character(s) added are \n or \r\n +depending on the platform. This defaults to true.

+
ReturnsDescription
void
+
+
+ + + +show(preserveFocus?: boolean): void +
+

Show the terminal panel and reveal this terminal in the UI.

+
+
+ + + + + +
ParameterDescription
preserveFocus?: boolean

When true the terminal will not take focus.

+
ReturnsDescription
void
+
+
+ +### TerminalOptions + + + +

Value-object describing what options a terminal should use.

+
+ +#### Properties + + + +cwd?: string +
+

A path for the current working directory to be used for the terminal.

+
+
+ + + +env?: +
+

Object with environment variables that will be added to the VS Code process.

+
+
+ + + +name?: string +
+

A human-readable string which will be used to represent the terminal in the UI.

+
+
+ + + +shellArgs?: string[] +
+

Args for the custom shell executable, this does not work on Windows (see #8429)

+
+
+ + + +shellPath?: string +
+

A path to a custom shell executable to be used in the terminal.

+
+
+ +### TextDocument + + + +

Represents a text document, such as a source file. Text documents have +lines and knowledge about an underlying resource like a file.

+
+ +#### Properties + + + +eol: EndOfLine +
+

The end of line sequence that is predominately +used in this document.

+
+
+ + + +fileName: string +
+

The file system path of the associated resource. Shorthand +notation for TextDocument.uri.fsPath. Independent of the uri scheme.

+
+
+ + + +isClosed: boolean +
+

true if the document have been closed. A closed document isn't synchronized anymore +and won't be re-used when the same resource is opened again.

+
+
+ + + +isDirty: boolean +
+

true if there are unpersisted changes.

+
+
+ + + +isUntitled: boolean +
+

Is this document representing an untitled file which has never been saved yet. Note that +this does not mean the document will be saved to disk, use uri.scheme +to figure out where a document will be saved, e.g. file, ftp etc.

+
+
+ + + +languageId: string +
+

The identifier of the language associated with this document.

+
+
+ + + +lineCount: number +
+

The number of lines in this document.

+
+
+ + + +uri: Uri +
+

The associated uri for this document.

+

Note that most documents use the file-scheme, which means they are files on disk. However, not all documents are +saved on disk and therefore the scheme must be checked before trying to access the underlying file or siblings on disk.

+ + +
+
+ + + +version: number +
+

The version number of this document (it will strictly increase after each +change, including undo/redo).

+
+
+ +#### Methods + + + +getText(range?: Range): string +
+

Get the text of this document. A substring can be retrieved by providing +a range. The range will be adjusted.

+
+
+ + + + + +
ParameterDescription
range?: Range

Include only the text included by the range.

+
ReturnsDescription
string

The text inside the provided range or the entire text.

+
+
+
+ + + +getWordRangeAtPosition(position: Position, regex?: RegExp): Range | undefined +
+

Get a word-range at the given position. By default words are defined by +common separators, like space, -, _, etc. In addition, per language custom +word definitions can be defined. It +is also possible to provide a custom regular expression.

+
    +
  • Note 1: A custom regular expression must not match the empty string and +if it does, it will be ignored.
    • +
  • Note 2: A custom regular expression will fail to match multiline strings +and in the name of speed regular expressions should not match words with +spaces. Use TextLine.text for more complex, non-wordy, scenarios.
    • +
+

The position will be adjusted.

+
+
+ + + + + + +
ParameterDescription
position: Position

A position.

+
regex?: RegExp

Optional regular expression that describes what a word is.

+
ReturnsDescription
Range | undefined

A range spanning a word, or undefined.

+
+
+
+ + + +lineAt(line: number): TextLine +
+

Returns a text line denoted by the line number. Note +that the returned object is not live and changes to the +document are not reflected.

+
+
+ + + + + +
ParameterDescription
line: number

A line number in [0, lineCount).

+
ReturnsDescription
TextLine

A line.

+
+
+
+ + + +lineAt(position: Position): TextLine +
+

Returns a text line denoted by the position. Note +that the returned object is not live and changes to the +document are not reflected.

+

The position will be adjusted.

+ +
+
+ + + + + +
ParameterDescription
position: Position

A position.

+
ReturnsDescription
TextLine

A line.

+
+
+
+ + + +offsetAt(position: Position): number +
+

Converts the position to a zero-based offset.

+

The position will be adjusted.

+
+
+ + + + + +
ParameterDescription
position: Position

A position.

+
ReturnsDescription
number

A valid zero-based offset.

+
+
+
+ + + +positionAt(offset: number): Position +
+

Converts a zero-based offset to a position.

+
+
+ + + + + +
ParameterDescription
offset: number

A zero-based offset.

+
ReturnsDescription
Position

A valid position.

+
+
+
+ + + +save(): Thenable<boolean> +
+

Save the underlying file.

+
+
+ + + +
ReturnsDescription
Thenable<boolean>

A promise that will resolve to true when the file +has been saved. If the file was not dirty or the save failed, +will return false.

+
+
+
+ + + +validatePosition(position: Position): Position +
+

Ensure a position is contained in the range of this document.

+
+
+ + + + + +
ParameterDescription
position: Position

A position.

+
ReturnsDescription
Position

The given position or a new, adjusted position.

+
+
+
+ + + +validateRange(range: Range): Range +
+

Ensure a range is completely contained in this document.

+
+
+ + + + + +
ParameterDescription
range: Range

A range.

+
ReturnsDescription
Range

The given range or a new, adjusted range.

+
+
+
+ +### TextDocumentChangeEvent + + + +

An event describing a transactional document change.

+
+ +#### Properties + + + +contentChanges: TextDocumentContentChangeEvent[] +
+

An array of content changes.

+
+
+ + + +document: TextDocument +
+

The affected document.

+
+
+ +### TextDocumentContentChangeEvent + + + +

An event describing an individual change in the text of a document.

+
+ +#### Properties + + + +range: Range +
+

The range that got replaced.

+
+
+ + + +rangeLength: number +
+

The length of the range that got replaced.

+
+
+ + + +rangeOffset: number +
+

The offset of the range that got replaced.

+
+
+ + + +text: string +
+

The new text for the range.

+
+
+ +### TextDocumentContentProvider + + + +

A text document content provider allows to add readonly documents +to the editor, such as source from a dll or generated html from md.

+

Content providers are registered +for a uri-scheme. When a uri with that scheme is to +be loaded the content provider is +asked.

+
+ +#### Events + + + +onDidChange?: Event<Uri> +
+

An event to signal a resource has changed.

+
+
+ +#### Methods + + + +provideTextDocumentContent(uri: Uri, token: CancellationToken): ProviderResult<string> +
+

Provide textual content for a given uri.

+

The editor will use the returned string-content to create a readonly +document. Resources allocated should be released when +the corresponding document has been closed.

+

Note: The contents of the created document might not be +identical to the provided text due to end-of-line-sequence normalization.

+
+
+ + + + + + +
ParameterDescription
uri: Uri

An uri which scheme matches the scheme this provider was registered for.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<string>

A string or a thenable that resolves to such.

+
+
+
+ +### TextDocumentSaveReason + + + +

Represents reasons why a text document is saved.

+
+ +#### Enumeration members + + + +AfterDelay +
+2 +
+ + + +FocusOut +
+3 +
+ + + +Manual +
+1 +
+ +### TextDocumentShowOptions + + + +

Represents options to configure the behavior of showing a document in an editor.

+
+ +#### Properties + + + +preserveFocus?: boolean +
+

An optional flag that when true will stop the editor from taking focus.

+
+
+ + + +preview?: boolean +
+

An optional flag that controls if an editor-tab will be replaced +with the next editor or if it will be kept.

+
+
+ + + +selection?: Range +
+

An optional selection to apply for the document in the editor.

+
+
+ + + +viewColumn?: ViewColumn +
+

An optional view column in which the editor should be shown. +The default is the active, other values are adjusted to +be Min(column, columnCount + 1), the active-column is +not adjusted. Use ViewColumn.Beside to open the +editor to the side of the currently active one.

+
+
+ +### TextDocumentWillSaveEvent + + + +

An event that is fired when a document will be saved.

+

To make modifications to the document before it is being saved, call the +waitUntil-function with a thenable +that resolves to an array of text edits.

+
+ +#### Properties + + + +document: TextDocument +
+

The document that will be saved.

+
+
+ + + +reason: TextDocumentSaveReason +
+

The reason why save was triggered.

+
+
+ +#### Methods + + + +waitUntil(thenable: Thenable<TextEdit[]>): void +
+

Allows to pause the event loop and to apply pre-save-edits. +Edits of subsequent calls to this function will be applied in order. The +edits will be ignored if concurrent modifications of the document happened.

+

Note: This function can only be called during event dispatch and not +in an asynchronous manner:

+ +
workspace.onWillSaveTextDocument(event => {
+    // async, will *throw* an error
+    setTimeout(() => event.waitUntil(promise));
+
+    // sync, OK
+    event.waitUntil(promise);
+})
+
+
+
+ + + + + +
ParameterDescription
thenable: Thenable<TextEdit[]>

A thenable that resolves to pre-save-edits.

+
ReturnsDescription
void
+
+
+ + + +waitUntil(thenable: Thenable<any>): void +
+

Allows to pause the event loop until the provided thenable resolved.

+

Note: This function can only be called during event dispatch.

+
+
+ + + + + +
ParameterDescription
thenable: Thenable<any>

A thenable that delays saving.

+
ReturnsDescription
void
+
+
+ +### TextEdit + + + +

A text edit represents edits that should be applied +to a document.

+
+ +#### Static + + + +delete(range: Range): TextEdit +
+

Utility to create a delete edit.

+
+
+ + + + + +
ParameterDescription
range: Range

A range.

+
ReturnsDescription
TextEdit

A new text edit object.

+
+
+
+ + + +insert(position: Position, newText: string): TextEdit +
+

Utility to create an insert edit.

+
+
+ + + + + + +
ParameterDescription
position: Position

A position, will become an empty range.

+
newText: string

A string.

+
ReturnsDescription
TextEdit

A new text edit object.

+
+
+
+ + + +replace(range: Range, newText: string): TextEdit +
+

Utility to create a replace edit.

+
+
+ + + + + + +
ParameterDescription
range: Range

A range.

+
newText: string

A string.

+
ReturnsDescription
TextEdit

A new text edit object.

+
+
+
+ + + +setEndOfLine(eol: EndOfLine): TextEdit +
+

Utility to create an eol-edit.

+
+
+ + + + + +
ParameterDescription
eol: EndOfLine

An eol-sequence

+
ReturnsDescription
TextEdit

A new text edit object.

+
+
+
+ +#### Constructors + + + +new TextEdit(range: Range, newText: string): TextEdit +
+

Create a new TextEdit.

+
+
+ + + + + + +
ParameterDescription
range: Range

A range.

+
newText: string

A string.

+
ReturnsDescription
TextEdit
+
+
+ +#### Properties + + + +newEol: EndOfLine +
+

The eol-sequence used in the document.

+

Note that the eol-sequence will be applied to the +whole document.

+
+
+ + + +newText: string +
+

The string this edit will insert.

+
+
+ + + +range: Range +
+

The range this edit applies to.

+
+
+ +### TextEditor + + + +

Represents an editor that is attached to a document.

+
+ +#### Properties + + + +document: TextDocument +
+

The document associated with this text editor. The document will be the same for the entire lifetime of this text editor.

+
+
+ + + +options: TextEditorOptions +
+

Text editor options.

+
+
+ + + +selection: Selection +
+

The primary selection on this text editor. Shorthand for TextEditor.selections[0].

+
+
+ + + +selections: Selection[] +
+

The selections in this text editor. The primary selection is always at index 0.

+
+
+ + + +viewColumn?: ViewColumn +
+

The column in which this editor shows. Will be undefined in case this +isn't one of the main editors, e.g an embedded editor, or when the editor +column is larger than three.

+
+
+ + + +visibleRanges: Range[] +
+

The current visible ranges in the editor (vertically). +This accounts only for vertical scrolling, and not for horizontal scrolling.

+
+
+ +#### Methods + + + +edit(callback: (editBuilder: TextEditorEdit) => void, options?: {undoStopAfter: boolean, undoStopBefore: boolean}): Thenable<boolean> +
+

Perform an edit on the document associated with this text editor.

+

The given callback-function is invoked with an edit-builder which must +be used to make edits. Note that the edit-builder is only valid while the +callback executes.

+
+
+ + + + + + +
ParameterDescription
callback: (editBuilder: TextEditorEdit) => void

A function which can create edits using an edit-builder.

+
options?: {undoStopAfter: boolean, undoStopBefore: boolean}

The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit.

+
ReturnsDescription
Thenable<boolean>

A promise that resolves with a value indicating if the edits could be applied.

+
+
+
+ + + +hide(): void +
+

Hide the text editor.

+
    +
  • deprecated - Use the command workbench.action.closeActiveEditor instead. +This method shows unexpected behavior and will be removed in the next major update.
    • +
+
+
+ + + +
ReturnsDescription
void
+
+
+ + + +insertSnippet(snippet: SnippetString, location?: Position | Range | Position[] | Range[], options?: {undoStopAfter: boolean, undoStopBefore: boolean}): Thenable<boolean> +
+

Insert a snippet and put the editor into snippet mode. "Snippet mode" +means the editor adds placeholders and additional cursors so that the user can complete +or accept the snippet.

+
+
+ + + + + + + +
ParameterDescription
snippet: SnippetString

The snippet to insert in this edit.

+
location?: Position | Range | Position[] | Range[]

Position or range at which to insert the snippet, defaults to the current editor selection or selections.

+
options?: {undoStopAfter: boolean, undoStopBefore: boolean}

The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit.

+
ReturnsDescription
Thenable<boolean>

A promise that resolves with a value indicating if the snippet could be inserted. Note that the promise does not signal +that the snippet is completely filled-in or accepted.

+
+
+
+ + + +revealRange(range: Range, revealType?: TextEditorRevealType): void +
+

Scroll as indicated by revealType in order to reveal the given range.

+
+
+ + + + + + +
ParameterDescription
range: Range

A range.

+
revealType?: TextEditorRevealType

The scrolling strategy for revealing range.

+
ReturnsDescription
void
+
+
+ + + +setDecorations(decorationType: TextEditorDecorationType, rangesOrOptions: Range[] | DecorationOptions[]): void +
+

Adds a set of decorations to the text editor. If a set of decorations already exists with +the given decoration type, they will be replaced.

+ +
+
+ + + + + + +
ParameterDescription
decorationType: TextEditorDecorationType

A decoration type.

+
rangesOrOptions: Range[] | DecorationOptions[]

Either ranges or more detailed options.

+
ReturnsDescription
void
+
+
+ + + +show(column?: ViewColumn): void +
+

Show the text editor.

+ +
+
+ + + + + +
ParameterDescription
column?: ViewColumn

The column in which to show this editor. +This method shows unexpected behavior and will be removed in the next major update.

+
ReturnsDescription
void
+
+
+ +### TextEditorCursorStyle + + + +

Rendering style of the cursor.

+
+ +#### Enumeration members + + + +Block +
+2 +
+ + + +BlockOutline +
+5 +
+ + + +Line +
+1 +
+ + + +LineThin +
+4 +
+ + + +Underline +
+3 +
+ + + +UnderlineThin +
+6 +
+ +### TextEditorDecorationType + + + +

Represents a handle to a set of decorations +sharing the same styling options in a text editor.

+

To get an instance of a TextEditorDecorationType use +createTextEditorDecorationType.

+
+ +#### Properties + + + +key: string +
+

Internal representation of the handle.

+
+
+ +#### Methods + + + +dispose(): void +
+

Remove this decoration type and all decorations on all text editors using it.

+
+
+ + + +
ReturnsDescription
void
+
+
+ +### TextEditorEdit + + + +

A complex edit that will be applied in one transaction on a TextEditor. +This holds a description of the edits and if the edits are valid (i.e. no overlapping regions, document was not changed in the meantime, etc.) +they can be applied on a document associated with a text editor.

+
+ +#### Methods + + + +delete(location: Range | Selection): void +
+

Delete a certain text region.

+
+
+ + + + + +
ParameterDescription
location: Range | Selection

The range this operation should remove.

+
ReturnsDescription
void
+
+
+ + + +insert(location: Position, value: string): void +
+

Insert text at a location. +You can use \r\n or \n in value and they will be normalized to the current document. +Although the equivalent text edit can be made with replace, insert will produce a different resulting selection (it will get moved).

+
+
+ + + + + + +
ParameterDescription
location: Position

The position where the new text should be inserted.

+
value: string

The new text this operation should insert.

+
ReturnsDescription
void
+
+
+ + + +replace(location: Position | Range | Selection, value: string): void +
+

Replace a certain text region with a new value. +You can use \r\n or \n in value and they will be normalized to the current document.

+
+
+ + + + + + +
ParameterDescription
location: Position | Range | Selection

The range this operation should remove.

+
value: string

The new text this operation should insert after removing location.

+
ReturnsDescription
void
+
+
+ + + +setEndOfLine(endOfLine: EndOfLine): void +
+

Set the end of line sequence.

+
+
+ + + + + +
ParameterDescription
endOfLine: EndOfLine

The new end of line for the document.

+
ReturnsDescription
void
+
+
+ +### TextEditorLineNumbersStyle + + + +

Rendering style of the line numbers.

+
+ +#### Enumeration members + + + +Off +
+0 +
+ + + +On +
+1 +
+ + + +Relative +
+2 +
+ +### TextEditorOptions + + + +

Represents a text editor's options.

+
+ +#### Properties + + + +cursorStyle?: TextEditorCursorStyle +
+

The rendering style of the cursor in this editor. +When getting a text editor's options, this property will always be present. +When setting a text editor's options, this property is optional.

+
+
+ + + +insertSpaces?: boolean | string +
+

When pressing Tab insert n spaces. +When getting a text editor's options, this property will always be a boolean (resolved). +When setting a text editor's options, this property is optional and it can be a boolean or "auto".

+
+
+ + + +lineNumbers?: TextEditorLineNumbersStyle +
+

Render relative line numbers w.r.t. the current line number. +When getting a text editor's options, this property will always be present. +When setting a text editor's options, this property is optional.

+
+
+ + + +tabSize?: number | string +
+

The size in spaces a tab takes. This is used for two purposes:

+
    +
  • the rendering width of a tab character;
    • +
  • the number of spaces to insert when insertSpaces is true.
    • +
+

When getting a text editor's options, this property will always be a number (resolved). +When setting a text editor's options, this property is optional and it can be a number or "auto".

+
+
+ +### TextEditorOptionsChangeEvent + + + +

Represents an event describing the change in a text editor's options.

+
+ +#### Properties + + + +options: TextEditorOptions +
+

The new value for the text editor's options.

+
+
+ + + +textEditor: TextEditor +
+

The text editor for which the options have changed.

+
+
+ +### TextEditorRevealType + + + +

Represents different reveal strategies in a text editor.

+
+ +#### Enumeration members + + + +AtTop +
+3 +
+ + + +Default +
+0 +
+ + + +InCenter +
+1 +
+ + + +InCenterIfOutsideViewport +
+2 +
+ +### TextEditorSelectionChangeEvent + + + +

Represents an event describing the change in a text editor's selections.

+
+ +#### Properties + + + +kind?: TextEditorSelectionChangeKind +
+

The change kind which has triggered this +event. Can be undefined.

+
+
+ + + +selections: Selection[] +
+

The new value for the text editor's selections.

+
+
+ + + +textEditor: TextEditor +
+

The text editor for which the selections have changed.

+
+
+ +### TextEditorSelectionChangeKind + + + +

Represents sources that can cause selection change events.

+
+ +#### Enumeration members + + + +Command +
+3 +
+ + + +Keyboard +
+1 +
+ + + +Mouse +
+2 +
+ +### TextEditorViewColumnChangeEvent + + + +

Represents an event describing the change of a text editor's view column.

+
+ +#### Properties + + + +textEditor: TextEditor +
+

The text editor for which the view column has changed.

+
+
+ + + +viewColumn: ViewColumn +
+

The new value for the text editor's view column.

+
+
+ +### TextEditorVisibleRangesChangeEvent + + + +

Represents an event describing the change in a text editor's visible ranges.

+
+ +#### Properties + + + +textEditor: TextEditor +
+

The text editor for which the visible ranges have changed.

+
+
+ + + +visibleRanges: Range[] +
+

The new value for the text editor's visible ranges.

+
+
+ +### TextLine + + + +

Represents a line of text, such as a line of source code.

+

TextLine objects are immutable. When a document changes, +previously retrieved lines will not represent the latest state.

+
+ +#### Properties + + + +firstNonWhitespaceCharacterIndex: number +
+

The offset of the first character which is not a whitespace character as defined +by /\s/. Note that if a line is all whitespaces the length of the line is returned.

+
+
+ + + +isEmptyOrWhitespace: boolean +
+

Whether this line is whitespace only, shorthand +for TextLine.firstNonWhitespaceCharacterIndex === TextLine.text.length.

+
+
+ + + +lineNumber: number +
+

The zero-based line number.

+
+
+ + + +range: Range +
+

The range this line covers without the line separator characters.

+
+
+ + + +rangeIncludingLineBreak: Range +
+

The range this line covers with the line separator characters.

+
+
+ + + +text: string +
+

The text of this line without the line separator characters.

+
+
+ +### ThemableDecorationAttachmentRenderOptions + + + +
+ +#### Properties + + + +backgroundColor?: string | ThemeColor +
+

CSS styling property that will be applied to the decoration attachment.

+
+
+ + + +border?: string +
+

CSS styling property that will be applied to the decoration attachment.

+
+
+ + + +borderColor?: string | ThemeColor +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +color?: string | ThemeColor +
+

CSS styling property that will be applied to the decoration attachment.

+
+
+ + + +contentIconPath?: string | Uri +
+

An absolute path or an URI to an image to be rendered in the attachment. Either an icon +or a text can be shown, but not both.

+
+
+ + + +contentText?: string +
+

Defines a text content that is shown in the attachment. Either an icon or a text can be shown, but not both.

+
+
+ + + +fontStyle?: string +
+

CSS styling property that will be applied to the decoration attachment.

+
+
+ + + +fontWeight?: string +
+

CSS styling property that will be applied to the decoration attachment.

+
+
+ + + +height?: string +
+

CSS styling property that will be applied to the decoration attachment.

+
+
+ + + +margin?: string +
+

CSS styling property that will be applied to the decoration attachment.

+
+
+ + + +textDecoration?: string +
+

CSS styling property that will be applied to the decoration attachment.

+
+
+ + + +width?: string +
+

CSS styling property that will be applied to the decoration attachment.

+
+
+ +### ThemableDecorationInstanceRenderOptions + + + +
+ +#### Properties + + + +after?: ThemableDecorationAttachmentRenderOptions +
+

Defines the rendering options of the attachment that is inserted after the decorated text.

+
+
+ + + +before?: ThemableDecorationAttachmentRenderOptions +
+

Defines the rendering options of the attachment that is inserted before the decorated text.

+
+
+ +### ThemableDecorationRenderOptions + + + +

Represents theme specific rendering styles for a text editor decoration.

+
+ +#### Properties + + + +after?: ThemableDecorationAttachmentRenderOptions +
+

Defines the rendering options of the attachment that is inserted after the decorated text.

+
+
+ + + +backgroundColor?: string | ThemeColor +
+

Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations. +Alternatively a color from the color registry can be referenced.

+
+
+ + + +before?: ThemableDecorationAttachmentRenderOptions +
+

Defines the rendering options of the attachment that is inserted before the decorated text.

+
+
+ + + +border?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +borderColor?: string | ThemeColor +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'border' for setting one or more of the individual border properties.

+
+
+ + + +borderRadius?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'border' for setting one or more of the individual border properties.

+
+
+ + + +borderSpacing?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'border' for setting one or more of the individual border properties.

+
+
+ + + +borderStyle?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'border' for setting one or more of the individual border properties.

+
+
+ + + +borderWidth?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'border' for setting one or more of the individual border properties.

+
+
+ + + +color?: string | ThemeColor +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +cursor?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +fontStyle?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +fontWeight?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +gutterIconPath?: string | Uri +
+

An absolute path or an URI to an image to be rendered in the gutter.

+
+
+ + + +gutterIconSize?: string +
+

Specifies the size of the gutter icon. +Available values are 'auto', 'contain', 'cover' and any percentage value. +For further information: https://msdn.microsoft.com/en-us/library/jj127316(v=vs.85).aspx

+
+
+ + + +letterSpacing?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +opacity?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +outline?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ + + +outlineColor?: string | ThemeColor +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'outline' for setting one or more of the individual outline properties.

+
+
+ + + +outlineStyle?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'outline' for setting one or more of the individual outline properties.

+
+
+ + + +outlineWidth?: string +
+

CSS styling property that will be applied to text enclosed by a decoration. +Better use 'outline' for setting one or more of the individual outline properties.

+
+
+ + + +overviewRulerColor?: string | ThemeColor +
+

The color of the decoration in the overview ruler. Use rgba() and define transparent colors to play well with other decorations.

+
+
+ + + +textDecoration?: string +
+

CSS styling property that will be applied to text enclosed by a decoration.

+
+
+ +### ThemeColor + + + +

A reference to one of the workbench colors as defined in https://code.visualstudio.com/docs/getstarted/theme-color-reference. +Using a theme color is preferred over a custom color as it gives theme authors and users the possibility to change the color.

+
+ +#### Constructors + + + +new ThemeColor(id: string): ThemeColor +
+

Creates a reference to a theme color.

+
+
+ + + + + +
ParameterDescription
id: string

of the color. The available colors are listed in https://code.visualstudio.com/docs/getstarted/theme-color-reference.

+
ReturnsDescription
ThemeColor
+
+
+ +### ThemeIcon + + + +

A reference to a named icon. Currently only File and Folder are supported. +Using a theme icon is preferred over a custom icon as it gives theme authors the possibility to change the icons.

+
+ +#### Static + + + +File: ThemeIcon +
+

Reference to a icon representing a file. The icon is taken from the current file icon theme or a placeholder icon.

+
+
+ + + +Folder: ThemeIcon +
+

Reference to a icon representing a folder. The icon is taken from the current file icon theme or a placeholder icon.

+
+
+ +#### Constructors + + + +new ThemeIcon(id: string): ThemeIcon +
+
+
+ + + + + +
ParameterDescription
id: string
ReturnsDescription
ThemeIcon
+
+
+ +### TreeDataProvider<T> + + + +

A data provider that provides tree data

+
+ +#### Events + + + +onDidChangeTreeData?: Event<T | undefined | null> +
+

An optional event to signal that an element or root has changed. +This will trigger the view to update the changed element/root and its children recursively (if shown). +To signal that root has changed, do not pass any argument or pass undefined or null.

+
+
+ +#### Methods + + + +getChildren(element?: T): ProviderResult<T[]> +
+

Get the children of element or root if no element is passed.

+
+
+ + + + + +
ParameterDescription
element?: T

The element from which the provider gets children. Can be undefined.

+
ReturnsDescription
ProviderResult<T[]>

Children of element or root if no element is passed.

+
+
+
+ + + +getParent(element: T): ProviderResult<T> +
+

Optional method to return the parent of element. +Return null or undefined if element is a child of root.

+

NOTE: This method should be implemented in order to access reveal API.

+
+
+ + + + + +
ParameterDescription
element: T

The element for which the parent has to be returned.

+
ReturnsDescription
ProviderResult<T>

Parent of element.

+
+
+
+ + + +getTreeItem(element: T): TreeItem | Thenable<TreeItem> +
+

Get TreeItem representation of the element

+
+
+ + + + + +
ParameterDescription
element: T

The element for which TreeItem representation is asked for.

+
ReturnsDescription
TreeItem | Thenable<TreeItem>

(#TreeItem) representation of the element

+
+
+
+ +### TreeItem + + + +
+ +#### Constructors + + + +new TreeItem(label: string, collapsibleState?: TreeItemCollapsibleState): TreeItem +
+
+
+ + + + + + +
ParameterDescription
label: string

A human-readable string describing this item

+
collapsibleState?: TreeItemCollapsibleState

(#TreeItemCollapsibleState) of the tree item. Default is TreeItemCollapsibleState.None

+
ReturnsDescription
TreeItem
+
+
+ + + +new TreeItem(resourceUri: Uri, collapsibleState?: TreeItemCollapsibleState): TreeItem +
+
+
+ + + + + + +
ParameterDescription
resourceUri: Uri

The uri of the resource representing this item.

+
collapsibleState?: TreeItemCollapsibleState

(#TreeItemCollapsibleState) of the tree item. Default is TreeItemCollapsibleState.None

+
ReturnsDescription
TreeItem
+
+
+ +#### Properties + + + +collapsibleState?: TreeItemCollapsibleState +
+

TreeItemCollapsibleState of the tree item.

+
+
+ + + +command?: Command +
+

The command that should be executed when the tree item is selected.

+
+
+ + + +contextValue?: string +
+

Context value of the tree item. This can be used to contribute item specific actions in the tree. +For example, a tree item is given a context value as folder. When contributing actions to view/item/context +using menus extension point, you can specify context value for key viewItem in when expression like viewItem == folder.

+ +
    "contributes": {
+        "menus": {
+            "view/item/context": [
+                {
+                    "command": "extension.deleteFolder",
+                    "when": "viewItem == folder"
+                }
+            ]
+        }
+    }
+

This will show action extension.deleteFolder only for items with contextValue is folder.

+
+
+ + + +description?: string | boolean +
+

A human readable string which is rendered less prominent. +When true, it is derived from resourceUri and when falsy, it is not shown.

+
+
+ + + +iconPath?: string | Uri | {dark: string | Uri, light: string | Uri} | ThemeIcon +
+

The icon path or ThemeIcon for the tree item. +When falsy, Folder Theme Icon is assigned, if item is collapsible otherwise File Theme Icon. +When a ThemeIcon is specified, icon is derived from the current file icon theme for the specified theme icon using resourceUri (if provided).

+
+
+ + + +id?: string +
+

Optional id for the tree item that has to be unique across tree. The id is used to preserve the selection and expansion state of the tree item.

+

If not provided, an id is generated using the tree item's label. Note that when labels change, ids will change and that selection and expansion state cannot be kept stable anymore.

+
+
+ + + +label?: string +
+

A human-readable string describing this item. When falsy, it is derived from resourceUri.

+
+
+ + + +resourceUri?: Uri +
+

The uri of the resource representing this item.

+

Will be used to derive the label, when it is not provided. +Will be used to derive the icon from current icon theme, when iconPath has ThemeIcon value.

+
+
+ + + +tooltip?: string | undefined +
+

The tooltip text when you hover over this item.

+
+
+ +### TreeItemCollapsibleState + + + +

Collapsible state of the tree item

+
+ +#### Enumeration members + + + +Collapsed +
+1 +
+ + + +Expanded +
+2 +
+ + + +None +
+0 +
+ +### TreeView<T> + + + +

Represents a Tree view

+
+ +#### Events + + + +onDidChangeSelection: Event<TreeViewSelectionChangeEvent<T>> +
+

Event that is fired when the selection has changed

+
+
+ + + +onDidChangeVisibility: Event<TreeViewVisibilityChangeEvent> +
+

Event that is fired when visibility has changed

+
+
+ + + +onDidCollapseElement: Event<TreeViewExpansionEvent<T>> +
+

Event that is fired when an element is collapsed

+
+
+ + + +onDidExpandElement: Event<TreeViewExpansionEvent<T>> +
+

Event that is fired when an element is expanded

+
+
+ +#### Static + + + +from(...disposableLikes: {dispose: () => any}[]): Disposable +
+

Combine many disposable-likes into one. Use this method +when having objects with a dispose function which are not +instances of Disposable.

+
+
+ + + + + +
ParameterDescription
...disposableLikes: {dispose: () => any}[]

Objects that have at least a dispose-function member.

+
ReturnsDescription
Disposable

Returns a new disposable which, upon dispose, will +dispose all provided disposables.

+
+
+
+ +#### Constructors + + + +new TreeView(callOnDispose: Function): TreeView +
+

Creates a new Disposable calling the provided function +on dispose.

+
+
+ + + + + +
ParameterDescription
callOnDispose: Function

Function that disposes something.

+
ReturnsDescription
TreeView
+
+
+ +#### Properties + + + +selection: T[] +
+

Currently selected elements.

+
+
+ + + +visible: boolean +
+

true if the tree view is visible otherwise false.

+
+
+ +#### Methods + + + +dispose(): any +
+

Dispose this object.

+
+
+ + + +
ReturnsDescription
any
+
+
+ + + +reveal(element: T, options?: {expand: boolean | number, focus: boolean, select: boolean}): Thenable<void> +
+

Reveals the given element in the tree view. +If the tree view is not visible then the tree view is shown and element is revealed.

+

By default revealed element is selected. +In order to not to select, set the option select to false. +In order to focus, set the option focus to true. +In order to expand the revealed element, set the option expand to true. To expand recursively set expand to the number of levels to expand. +NOTE: You can expand only to 3 levels maximum.

+

NOTE: TreeDataProvider is required to implement getParent method to access this API.

+
+
+ + + + + + +
ParameterDescription
element: T
options?: {expand: boolean | number, focus: boolean, select: boolean}
ReturnsDescription
Thenable<void>
+
+
+ +### TreeViewExpansionEvent<T> + + + +

The event that is fired when an element in the TreeView is expanded or collapsed

+
+ +#### Properties + + + +element: T +
+

Element that is expanded or collapsed.

+
+
+ +### TreeViewOptions<T> + + + +

Options for creating a TreeView

+
+ +#### Properties + + + +showCollapseAll?: boolean +
+

Whether to show collapse all action or not.

+
+
+ + + +treeDataProvider: TreeDataProvider<T> +
+

A data provider that provides tree data.

+
+
+ +### TreeViewSelectionChangeEvent<T> + + + +

The event that is fired when there is a change in tree view's selection

+
+ +#### Properties + + + +selection: T[] +
+

Selected elements.

+
+
+ +### TreeViewVisibilityChangeEvent + + + +

The event that is fired when there is a change in tree view's visibility

+
+ +#### Properties + + + +visible: boolean +
+

true if the tree view is visible otherwise false.

+
+
+ +### TypeDefinitionProvider + + + +

The type definition provider defines the contract between extensions and +the go to type definition feature.

+
+ +#### Methods + + + +provideTypeDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | DefinitionLink[]> +
+

Provide the type definition of the symbol at the given position and document.

+
+
+ + + + + + + +
ParameterDescription
document: TextDocument

The document in which the command was invoked.

+
position: Position

The position at which the command was invoked.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<Definition | DefinitionLink[]>

A definition or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined or null.

+
+
+
+ +### Uri + + + +

A universal resource identifier representing either a file on disk +or another resource, like untitled resources.

+
+ +#### Static + + + +file(path: string): Uri +
+

Create an URI from a file system path. The scheme +will be file.

+

The difference between Uri#parse and Uri#file is that the latter treats the argument +as path, not as stringified-uri. E.g. Uri.file(path) is not the same as +Uri.parse('file://' + path) because the path might contain characters that are +interpreted (# and ?). See the following sample:

+ +
const good = URI.file('/coding/c#/project1');
+good.scheme === 'file';
+good.path === '/coding/c#/project1';
+good.fragment === '';
+
+const bad = URI.parse('file://' + '/coding/c#/project1');
+bad.scheme === 'file';
+bad.path === '/coding/c'; // path is now broken
+bad.fragment === '/project1';
+
+
+
+ + + + + +
ParameterDescription
path: string

A file system or UNC path.

+
ReturnsDescription
Uri

A new Uri instance.

+
+
+
+ + + +parse(value: string): Uri +
+

Create an URI from a string, e.g. http://www.msft.com/some/path, +file:///usr/home, or scheme:with/path.

+ +
+
+ + + + + +
ParameterDescription
value: string

The string value of an Uri.

+
ReturnsDescription
Uri

A new Uri instance.

+
+
+
+ +#### Constructors + + + +new Uri(scheme: string, authority: string, path: string, query: string, fragment: string): Uri +
+

Use the file and parse factory functions to create new Uri objects.

+
+
+ + + + + + + + + +
ParameterDescription
scheme: string
authority: string
path: string
query: string
fragment: string
ReturnsDescription
Uri
+
+
+ +#### Properties + + + +authority: string +
+

Authority is the www.msft.com part of http://www.msft.com/some/path?query#fragment. +The part between the first double slashes and the next slash.

+
+
+ + + +fragment: string +
+

Fragment is the fragment part of http://www.msft.com/some/path?query#fragment.

+
+
+ + + +fsPath: string +
+

The string representing the corresponding file system path of this Uri.

+

Will handle UNC paths and normalize windows drive letters to lower-case. Also +uses the platform specific path separator.

+
    +
  • Will not validate the path for invalid characters and semantics.
    • +
  • Will not look at the scheme of this Uri.
    • +
  • The resulting string shall not be used for display purposes but +for disk operations, like readFile et al.
    • +
+

The difference to the path-property is the use of the platform specific +path separator and the handling of UNC paths. The sample below outlines the difference:

+ +
const u = URI.parse('file://server/c$/folder/file.txt')
+u.authority === 'server'
+u.path === '/shares/c$/file.txt'
+u.fsPath === '\\server\c$\folder\file.txt'
+
+
+
+ + + +path: string +
+

Path is the /some/path part of http://www.msft.com/some/path?query#fragment.

+
+
+ + + +query: string +
+

Query is the query part of http://www.msft.com/some/path?query#fragment.

+
+
+ + + +scheme: string +
+

Scheme is the http part of http://www.msft.com/some/path?query#fragment. +The part before the first colon.

+
+
+ +#### Methods + + + +toJSON(): any +
+

Returns a JSON representation of this Uri.

+
+
+ + + +
ReturnsDescription
any

An object.

+
+
+
+ + + +toString(skipEncoding?: boolean): string +
+

Returns a string representation of this Uri. The representation and normalization +of a URI depends on the scheme.

+
    +
  • The resulting string can be safely used with Uri.parse.
    • +
  • The resulting string shall not be used for display purposes.
    • +
+

Note that the implementation will encode aggressive which often leads to unexpected, +but not incorrect, results. For instance, colons are encoded to %3A which might be unexpected +in file-uri. Also & and = will be encoded which might be unexpected for http-uris. For stability +reasons this cannot be changed anymore. If you suffer from too aggressive encoding you should use +the skipEncoding-argument: uri.toString(true).

+
+
+ + + + + +
ParameterDescription
skipEncoding?: boolean

Do not percentage-encode the result, defaults to false. Note that + the # and ? characters occurring in the path will always be encoded.

+
ReturnsDescription
string

A string representation of this Uri.

+
+
+
+ + + +with(change: {authority: string, fragment: string, path: string, query: string, scheme: string}): Uri +
+

Derive a new Uri from this Uri.

+ +
let file = Uri.parse('before:some/file/path');
+let other = file.with({ scheme: 'after' });
+assert.ok(other.toString() === 'after:some/file/path');
+
+
+
+ + + + + +
ParameterDescription
change: {authority: string, fragment: string, path: string, query: string, scheme: string}

An object that describes a change to this Uri. To unset components use null or + the empty string.

+
ReturnsDescription
Uri

A new Uri that reflects the given change. Will return this Uri if the change + is not changing anything.

+
+
+
+ +### UriHandler + + + +

A uri handler is responsible for handling system-wide uris.

+ +
+ +#### Methods + + + +handleUri(uri: Uri): ProviderResult<void> +
+

Handle the provided system-wide uri.

+ +
+
+ + + + + +
ParameterDescription
uri: Uri
ReturnsDescription
ProviderResult<void>
+
+
+ +### ViewColumn + + + +

Denotes a location of an editor in the window. Editors can be arranged in a grid +and each column represents one editor location in that grid by counting the editors +in order of their appearance.

+
+ +#### Enumeration members + + + +Active +
+ -1 +
+ + + +Beside +
+ -2 +
+ + + +Eight +
+8 +
+ + + +Five +
+5 +
+ + + +Four +
+4 +
+ + + +Nine +
+9 +
+ + + +One +
+1 +
+ + + +Seven +
+7 +
+ + + +Six +
+6 +
+ + + +Three +
+3 +
+ + + +Two +
+2 +
+ +### Webview + + + +

A webview displays html content, like an iframe.

+
+ +#### Events + + + +onDidReceiveMessage: Event<any> +
+

Fired when the webview content posts a message.

+
+
+ +#### Properties + + + +html: string +
+

Contents of the webview.

+

Should be a complete html document.

+
+
+ + + +options: WebviewOptions +
+

Content settings for the webview.

+
+
+ +#### Methods + + + +postMessage(message: any): Thenable<boolean> +
+

Post a message to the webview content.

+

Messages are only delivered if the webview is visible.

+
+
+ + + + + +
ParameterDescription
message: any

Body of the message.

+
ReturnsDescription
Thenable<boolean>
+
+
+ +### WebviewOptions + + + +

Content settings for a webview.

+
+ +#### Properties + + + +enableCommandUris?: boolean +
+

Controls whether command uris are enabled in webview content or not.

+

Defaults to false.

+
+
+ + + +enableScripts?: boolean +
+

Controls whether scripts are enabled in the webview content or not.

+

Defaults to false (scripts-disabled).

+
+
+ + + +localResourceRoots?: ReadonlyArray<Uri> +
+

Root paths from which the webview can load local (filesystem) resources using the vscode-resource: scheme.

+

Default to the root folders of the current workspace plus the extension's install directory.

+

Pass in an empty array to disallow access to any local resources.

+
+
+ +### WebviewPanel + + + +

A panel that contains a webview.

+
+ +#### Events + + + +onDidChangeViewState: Event<WebviewPanelOnDidChangeViewStateEvent> +
+

Fired when the panel's view state changes.

+
+
+ + + +onDidDispose: Event<void> +
+

Fired when the panel is disposed.

+

This may be because the user closed the panel or because .dispose() was +called on it.

+

Trying to use the panel after it has been disposed throws an exception.

+
+
+ +#### Properties + + + +active: boolean +
+

Whether the panel is active (focused by the user).

+
+
+ + + +iconPath?: Uri | {dark: Uri, light: Uri} +
+

Icon for the panel shown in UI.

+
+
+ + + +options: WebviewPanelOptions +
+

Content settings for the webview panel.

+
+
+ + + +title: string +
+

Title of the panel shown in UI.

+
+
+ + + +viewColumn?: ViewColumn +
+

Editor position of the panel. This property is only set if the webview is in +one of the editor view columns.

+
+
+ + + +viewType: string +
+

Identifies the type of the webview panel, such as 'markdown.preview'.

+
+
+ + + +visible: boolean +
+

Whether the panel is visible.

+
+
+ + + +webview: Webview +
+

Webview belonging to the panel.

+
+
+ +#### Methods + + + +dispose(): any +
+

Dispose of the webview panel.

+

This closes the panel if it showing and disposes of the resources owned by the webview. +Webview panels are also disposed when the user closes the webview panel. Both cases +fire the onDispose event.

+
+
+ + + +
ReturnsDescription
any
+
+
+ + + +reveal(viewColumn?: ViewColumn, preserveFocus?: boolean): void +
+

Show the webview panel in a given column.

+

A webview panel may only show in a single column at a time. If it is already showing, this +method moves it to a new column.

+
+
+ + + + + + +
ParameterDescription
viewColumn?: ViewColumn

View column to show the panel in. Shows in the current viewColumn if undefined.

+
preserveFocus?: boolean

When true, the webview will not take focus.

+
ReturnsDescription
void
+
+
+ +### WebviewPanelOnDidChangeViewStateEvent + + + +

Event fired when a webview panel's view state changes.

+
+ +#### Properties + + + +webviewPanel: WebviewPanel +
+

Webview panel whose view state changed.

+
+
+ +### WebviewPanelOptions + + + +

Content settings for a webview panel.

+
+ +#### Properties + + + +enableFindWidget?: boolean +
+

Controls if the find widget is enabled in the panel.

+

Defaults to false.

+
+
+ + + +retainContextWhenHidden?: boolean +
+

Controls if the webview panel's content (iframe) is kept around even when the panel +is no longer visible.

+

Normally the webview panel's html context is created when the panel becomes visible +and destroyed when it is hidden. Extensions that have complex state +or UI can set the retainContextWhenHidden to make VS Code keep the webview +context around, even when the webview moves to a background tab. When a webview using +retainContextWhenHidden becomes hidden, its scripts and other dynamic content are suspended. +When the panel becomes visible again, the context is automatically restored +in the exact same state it was in originally. You cannot send messages to a +hidden webview, even with retainContextWhenHidden enabled.

+

retainContextWhenHidden has a high memory overhead and should only be used if +your panel's context cannot be quickly saved and restored.

+
+
+ +### WebviewPanelSerializer + + + +

Restore webview panels that have been persisted when vscode shuts down.

+

There are two types of webview persistence:

+
    +
  • Persistence within a session.
    • +
  • Persistence across sessions (across restarts of VS Code).
    • +
+

A WebviewPanelSerializer is only required for the second case: persisting a webview across sessions.

+

Persistence within a session allows a webview to save its state when it becomes hidden +and restore its content from this state when it becomes visible again. It is powered entirely +by the webview content itself. To save off a persisted state, call acquireVsCodeApi().setState() with +any json serializable object. To restore the state again, call getState()

+ +
// Within the webview
+const vscode = acquireVsCodeApi();
+
+// Get existing state
+const oldState = vscode.getState() || { value: 0 };
+
+// Update state
+setState({ value: oldState.value + 1 })
+
+

A WebviewPanelSerializer extends this persistence across restarts of VS Code. When the editor is shutdown, +VS Code will save off the state from setState of all webviews that have a serializer. When the +webview first becomes visible after the restart, this state is passed to deserializeWebviewPanel. +The extension can then restore the old WebviewPanel from this state.

+
+ +#### Methods + + + +deserializeWebviewPanel(webviewPanel: WebviewPanel, state: any): Thenable<void> +
+

Restore a webview panel from its seriailzed state.

+

Called when a serialized webview first becomes visible.

+
+
+ + + + + + +
ParameterDescription
webviewPanel: WebviewPanel

Webview panel to restore. The serializer should take ownership of this panel. The +serializer must restore the webview's .html and hook up all webview events.

+
state: any

Persisted state from the webview content.

+
ReturnsDescription
Thenable<void>

Thanble indicating that the webview has been fully restored.

+
+
+
+ +### WindowState + + + +

Represents the state of a window.

+
+ +#### Properties + + + +focused: boolean +
+

Whether the current window is focused.

+
+
+ +### WorkspaceConfiguration + + + +

Represents the configuration. It is a merged view of

+
    +
  • Default configuration
    • +
  • Global configuration
    • +
  • Workspace configuration (if available)
    • +
  • Workspace folder configuration of the requested resource (if available)
    • +
+

Global configuration comes from User Settings and shadows Defaults.

+

Workspace configuration comes from Workspace Settings and shadows Global configuration.

+

Workspace Folder configuration comes from .vscode folder under one of the workspace folders.

+

Note: Workspace and Workspace Folder configurations contains launch and tasks settings. Their basename will be +part of the section identifier. The following snippets shows how to retrieve all configurations +from launch.json:

+ +
// launch.json configuration
+const config = workspace.getConfiguration('launch', vscode.window.activeTextEditor.document.uri);
+
+// retrieve values
+const values = config.get('configurations');
+
+

Refer to Settings for more information.

+
+ +#### Methods + + + +get<T>(section: string): T | undefined +
+

Return a value from this configuration.

+
+
+ + + + + +
ParameterDescription
section: string

Configuration name, supports dotted names.

+
ReturnsDescription
T | undefined

The value section denotes or undefined.

+
+
+
+ + + +get<T>(section: string, defaultValue: T): T +
+

Return a value from this configuration.

+
+
+ + + + + + +
ParameterDescription
section: string

Configuration name, supports dotted names.

+
defaultValue: T

A value should be returned when no value could be found, is undefined.

+
ReturnsDescription
T

The value section denotes or the default.

+
+
+
+ + + +has(section: string): boolean +
+

Check if this configuration has a certain value.

+
+
+ + + + + +
ParameterDescription
section: string

Configuration name, supports dotted names.

+
ReturnsDescription
boolean

true if the section doesn't resolve to undefined.

+
+
+
+ + + +inspect<T>(section: string): {defaultValue: T, globalValue: T, key: string, workspaceFolderValue: T, workspaceValue: T} | undefined +
+

Retrieve all information about a configuration setting. A configuration value +often consists of a default value, a global or installation-wide value, +a workspace-specific value and a folder-specific value.

+

The effective value (returned by get) +is computed like this: defaultValue overwritten by globalValue, +globalValue overwritten by workspaceValue. workspaceValue overwritten by workspaceFolderValue. +Refer to Settings Inheritance +for more information.

+

Note: The configuration name must denote a leaf in the configuration tree +(editor.fontSize vs editor) otherwise no result is returned.

+
+
+ + + + + +
ParameterDescription
section: string

Configuration name, supports dotted names.

+
ReturnsDescription
{defaultValue: T, globalValue: T, key: string, workspaceFolderValue: T, workspaceValue: T} | undefined

Information about a configuration setting or undefined.

+
+
+
+ + + +update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean): Thenable<void> +
+

Update a configuration value. The updated configuration values are persisted.

+

A value can be changed in

+ +

Note 1: Setting a global value in the presence of a more specific workspace value +has no observable effect in that workspace, but in others. Setting a workspace value +in the presence of a more specific folder value has no observable effect for the resources +under respective folder, but in others. Refer to +Settings Inheritance for more information.

+

Note 2: To remove a configuration value use undefined, like so: config.update('somekey', undefined)

+

Will throw error when

+
    +
  • Writing a configuration which is not registered.
    • +
  • Writing a configuration to workspace or folder target when no workspace is opened
    • +
  • Writing a configuration to folder target when there is no folder settings
    • +
  • Writing to folder target without passing a resource when getting the configuration (workspace.getConfiguration(section, resource))
    • +
  • Writing a window configuration to folder target
    • +
+
+
+ + + + + + + +
ParameterDescription
section: string

Configuration name, supports dotted names.

+
value: any

The new value.

+
configurationTarget?: ConfigurationTarget | boolean

The configuration target or a boolean value.

+ +
- If `true` configuration target is `ConfigurationTarget.Global`.
+- If `false` configuration target is `ConfigurationTarget.Workspace`.
+- If `undefined` or `null` configuration target is
+`ConfigurationTarget.WorkspaceFolder` when configuration is resource specific
+`ConfigurationTarget.Workspace` otherwise.
+
ReturnsDescription
Thenable<void>
+
+
+ +### WorkspaceEdit + + + +

A workspace edit is a collection of textual and files changes for +multiple resources and documents.

+

Use the applyEdit-function to apply a workspace edit.

+
+ +#### Properties + + + +size: number +
+

The number of affected resources of textual or resource changes.

+
+
+ +#### Methods + + + +createFile(uri: Uri, options?: {ignoreIfExists: boolean, overwrite: boolean}): void +
+

Create a regular file.

+
+
+ + + + + + +
ParameterDescription
uri: Uri

Uri of the new file..

+
options?: {ignoreIfExists: boolean, overwrite: boolean}

Defines if an existing file should be overwritten or be +ignored. When overwrite and ignoreIfExists are both set overwrite wins.

+
ReturnsDescription
void
+
+
+ + + +delete(uri: Uri, range: Range): void +
+

Delete the text at the given range.

+
+
+ + + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
range: Range

A range.

+
ReturnsDescription
void
+
+
+ + + +deleteFile(uri: Uri, options?: {ignoreIfNotExists: boolean, recursive: boolean}): void +
+

Delete a file or folder.

+
+
+ + + + + + +
ParameterDescription
uri: Uri

The uri of the file that is to be deleted.

+
options?: {ignoreIfNotExists: boolean, recursive: boolean}
ReturnsDescription
void
+
+
+ + + +entries(): [Uri, TextEdit[]][] +
+

Get all text edits grouped by resource.

+
+
+ + + +
ReturnsDescription
[Uri, TextEdit[]][]

A shallow copy of [Uri, TextEdit[]]-tuples.

+
+
+
+ + + +get(uri: Uri): TextEdit[] +
+

Get the text edits for a resource.

+
+
+ + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
ReturnsDescription
TextEdit[]

An array of text edits.

+
+
+
+ + + +has(uri: Uri): boolean +
+

Check if a text edit for a resource exists.

+
+
+ + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
ReturnsDescription
boolean

true if the given resource will be touched by this edit.

+
+
+
+ + + +insert(uri: Uri, position: Position, newText: string): void +
+

Insert the given text at the given position.

+
+
+ + + + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
position: Position

A position.

+
newText: string

A string.

+
ReturnsDescription
void
+
+
+ + + +renameFile(oldUri: Uri, newUri: Uri, options?: {ignoreIfExists: boolean, overwrite: boolean}): void +
+

Rename a file or folder.

+
+
+ + + + + + + +
ParameterDescription
oldUri: Uri

The existing file.

+
newUri: Uri

The new location.

+
options?: {ignoreIfExists: boolean, overwrite: boolean}

Defines if existing files should be overwritten or be +ignored. When overwrite and ignoreIfExists are both set overwrite wins.

+
ReturnsDescription
void
+
+
+ + + +replace(uri: Uri, range: Range, newText: string): void +
+

Replace the given range with given text for the given resource.

+
+
+ + + + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
range: Range

A range.

+
newText: string

A string.

+
ReturnsDescription
void
+
+
+ + + +set(uri: Uri, edits: TextEdit[]): void +
+

Set (and replace) text edits for a resource.

+
+
+ + + + + + +
ParameterDescription
uri: Uri

A resource identifier.

+
edits: TextEdit[]

An array of text edits.

+
ReturnsDescription
void
+
+
+ +### WorkspaceFolder + + + +

A workspace folder is one of potentially many roots opened by the editor. All workspace folders +are equal which means there is no notion of an active or master workspace folder.

+
+ +#### Properties + + + +index: number +
+

The ordinal number of this workspace folder.

+
+
+ + + +name: string +
+

The name of this workspace folder. Defaults to +the basename of its uri-path

+
+
+ + + +uri: Uri +
+

The associated uri for this workspace folder.

+

Note: The Uri-type was intentionally chosen such that future releases of the editor can support +workspace folders that are not stored on the local disk, e.g. ftp://server/workspaces/foo.

+
+
+ +### WorkspaceFolderPickOptions + + + +

Options to configure the behaviour of the workspace folder pick UI.

+
+ +#### Properties + + + +ignoreFocusOut?: boolean +
+

Set to true to keep the picker open when focus moves to another part of the editor or to another window.

+
+
+ + + +placeHolder?: string +
+

An optional string to show as place holder in the input box to guide the user what to pick on.

+
+
+ +### WorkspaceFoldersChangeEvent + + + +

An event describing a change to the set of workspace folders.

+
+ +#### Properties + + + +added: WorkspaceFolder[] +
+

Added workspace folders.

+
+
+ + + +removed: WorkspaceFolder[] +
+

Removed workspace folders.

+
+
+ +### WorkspaceSymbolProvider + + + +

The workspace symbol provider interface defines the contract between extensions and +the symbol search-feature.

+
+ +#### Methods + + + +provideWorkspaceSymbols(query: string, token: CancellationToken): ProviderResult<SymbolInformation[]> +
+

Project-wide search for a symbol matching the given query string.

+

The query-parameter should be interpreted in a relaxed way as the editor will apply its own highlighting +and scoring on the results. A good rule of thumb is to match case-insensitive and to simply check that the +characters of query appear in their order in a candidate symbol. Don't use prefix, substring, or similar +strict matching.

+

To improve performance implementors can implement resolveWorkspaceSymbol and then provide symbols with partial +location-objects, without a range defined. The editor will then call +resolveWorkspaceSymbol for selected symbols only, e.g. when opening a workspace symbol.

+
+
+ + + + + + +
ParameterDescription
query: string

A non-empty query string.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<SymbolInformation[]>

An array of document highlights or a thenable that resolves to such. The lack of a result can be +signaled by returning undefined, null, or an empty array.

+
+
+
+ + + +resolveWorkspaceSymbol(symbol: SymbolInformation, token: CancellationToken): ProviderResult<SymbolInformation> +
+

Given a symbol fill in its location. This method is called whenever a symbol +is selected in the UI. Providers can implement this method and return incomplete symbols from +provideWorkspaceSymbols which often helps to improve +performance.

+
+
+ + + + + + +
ParameterDescription
symbol: SymbolInformation

The symbol that is to be resolved. Guaranteed to be an instance of an object returned from an +earlier call to provideWorkspaceSymbols.

+
token: CancellationToken

A cancellation token.

+
ReturnsDescription
ProviderResult<SymbolInformation>

The resolved symbol or a thenable that resolves to that. When no result is returned, +the given symbol is used.

+
+
+
+ diff --git a/api/references/vscode-api.template b/api/references/vscode-api.template new file mode 100644 index 0000000000000000000000000000000000000000..ce62fb130a57da1ea4dddadc390d3c39842195f3 --- /dev/null +++ b/api/references/vscode-api.template @@ -0,0 +1,74 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 8CEBCDF8-4F0A-4C81-A904-3DEA43480EA6 +DateApproved: 3/7/2019 + +VSCodeCommitHash: 2380981c97a07816a3d1c10edf1fb678463dc215 +VSCodeVersion: 1.32.0 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Visual Studio Code extensions (plug-in) API Reference. +--- + +# VS Code API + +**VS Code API** is a set of JavaScript APIs that you can invoke in your Visual Studio Code extension. This page lists all VS Code APIs available to extension authors. + +## API Patterns + +These are some of the common patterns we use in the VS Code API. + +### Promises + +The VS Code API represents asynchronous operations with [promises](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise). From extensions, __any__ type of promise can be returned, like ES6, WinJS, A+, etc. + +Being independent of a specific promise library is expressed in the API by the `Thenable`-type. `Thenable` represents the common denominator which is the [then](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/then) method. + +In most cases the use of promises is optional and when VS Code calls into an extension, it can handle the _result type_ as well as a `Thenable` of the _result type_. When the use of a promise is optional, the API indicates this by returning `or`-types. + +```typescript +provideNumber(): number | Thenable +``` + +### Cancellation Tokens + +Often operations are started on volatile state which changes before operations can finish. For instance, computing IntelliSense starts and the user continues to type making the result of that operation obsolete. + +APIs that are exposed to such behavior will get passed a `CancellationToken` on which you can check for cancellation (`isCancellationRequested`) or get notified when cancellation occurs (`onCancellationRequested`). The cancellation token is usually the last parameter of a function call and optional. + +### Disposables + +The VS Code API uses the [dispose pattern](https://en.wikipedia.org/wiki/Dispose_pattern) for resources that are obtained from VS Code. This applies to event listening, commands, interacting with the UI, and various language contributions. + +For instance, the `setStatusBarMessage(value: string)` function returns a `Disposable` which upon calling `dispose` removes the message again. + +### Events + +Events in the VS Code API are exposed as functions which you call with a listener-function to subscribe. Calls to subscribe return a `Disposable` which removes the event listener upon dispose. + +```javascript +var listener = function(event) { + console.log("It happened", event); +}; + +// start listening +var subscription = fsWatcher.onDidDelete(listener); + +// do more stuff + +subscription.dispose(); // stop listening +``` + +Names of events follow the `on[Will|Did]VerbNoun?` pattern. The name signals if the event is going to happen *(onWill)* or already happened *(onDid)*, what happened *(verb)*, and the context *(noun)* unless obvious from the context. + +An example from the VS Code API is `window.onDidChangeActiveTextEditor` which is an event fired when the active text editor *(noun)* has been (*onDid*) changed (*verb*). + +### Strict null + +The VS Code API uses the `undefined` and `null` TypeScript types where appropriate to support [strict null checking](https://github.com/Microsoft/TypeScript/pull/7140). + +## API Listing + +This listing is compiled from the [`vscode.d.ts`](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.d.ts) file from the VS Code repository. + +{$ Content $} \ No newline at end of file diff --git a/api/toc.json b/api/toc.json new file mode 100644 index 0000000000000000000000000000000000000000..cb6cd5ce50650bf7032d5b63a84360979e457d4a --- /dev/null +++ b/api/toc.json @@ -0,0 +1,89 @@ +[ + { + "name": "Get Started", + "area": "get-started", + "topics": [ + ["Your First Extension", "/api/get-started/your-first-extension"], + ["Extension Anatomy", "/api/get-started/extension-anatomy"], + ["Wrapping Up", "/api/get-started/wrapping-up"] + ] + }, + { + "name": "Working With Extensions", + "area": "working-with-extensions", + "topics": [ + ["Testing Extension", "/api/working-with-extensions/testing-extension"], + ["Publishing Extension", "/api/working-with-extensions/publishing-extension"], + ["Bundling Extension", "/api/working-with-extensions/bundling-extension"], + ["Continuous Integration", "/api/working-with-extensions/continuous-integration"] + // ["Profiling Extension", "/api/advanced-topics/profiling-extension"], + ] + }, + { + "name": "Extension Capabilities", + "area": "extension-capabilities", + "topics": [ + ["Overview", "/api/extension-capabilities/overview"], + ["Common Capabilities", "/api/extension-capabilities/common-capabilities"], + ["Theming", "/api/extension-capabilities/theming"], + ["Extending Workbench", "/api/extension-capabilities/extending-workbench"] + ] + }, + { + "name": "Extension Guides", + "area": "extension-guides", + "topics": [ + ["Overview", "/api/extension-guides/overview"], + ["Command", "/api/extension-guides/command"], + ["Color Theme", "/api/extension-guides/color-theme"], + ["Icon Theme", "/api/extension-guides/icon-theme"], + ["Tree View", "/api/extension-guides/tree-view"], + ["Webview", "/api/extension-guides/webview"], + ["Virtual Documents", "/api/extension-guides/virtual-documents"], + ["Task Provider", "/api/extension-guides/task-provider"], + ["Source Control", "/api/extension-guides/scm-provider"], + ["Debugger Extension", "/api/extension-guides/debugger-extension"], + ["Markdown Extension", "/api/extension-guides/markdown-extension"] + ] + }, + { + "name": "Language Extensions", + "area": "language-extensions", + "topics": [ + ["Overview", "/api/language-extensions/overview"], + ["Syntax Highlight Guide", "/api/language-extensions/syntax-highlight-guide"], + ["Snippet Guide", "/api/language-extensions/snippet-guide"], + ["Language Configuration Guide", "/api/language-extensions/language-configuration-guide"], + ["Programmatic Language Features", "/api/language-extensions/programmatic-language-features"], + // ["Smart Editing Guide", "/api/language-extensions/smart-editing-guide"], + ["Language Server Extension Guide", "/api/language-extensions/language-server-extension-guide"] + ] + }, + { + "name": "Advanced Topics", + "area": "advanced-topics", + "topics": [ + ["Extension Host", "/api/advanced-topics/extension-host"], + // ["Extension Dependencies", "/api/advanced-topics/extension-dependencies"], + ["Using Proposed API", "/api/advanced-topics/using-proposed-api"], + // ["Exposing API", "/api/advanced-topics/exposing-api"], + // ["Native Modules", "/api/advanced-topics/native-modules"], + // ["Web Assembly", "/api/advanced-topics/web-assembly"], + // ["Internationalization", "/api/advanced-topics/internationalization"] + ] + }, + { + "name": "References", + "area": "references", + "topics": [ + ["VS Code API ", "/api/references/vscode-api"], + ["Contribution Points", "/api/references/contribution-points"], + ["Activation Events", "/api/references/activation-events"], + ["Extension Manifest", "/api/references/extension-manifest"], + ["Commands", "/api/references/commands"], + ["Theme Color", "/api/references/theme-color"], + ["Icons In Labels", "/api/references/icons-in-labels"], + ["Document Selector", "/api/references/document-selector"] + ] + } +] diff --git a/api/working-with-extensions/bundling-extension.md b/api/working-with-extensions/bundling-extension.md new file mode 100644 index 0000000000000000000000000000000000000000..478750df5ccfdfc2df44dacf3a24c4c505a2d2a3 --- /dev/null +++ b/api/working-with-extensions/bundling-extension.md @@ -0,0 +1,172 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 26f0c0d6-1ea8-4cc1-bd10-9fa744056e7c +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Bundling Visual Studio Code extensions (plug-ins) with webpack. +--- + +# Bundling Extension + +Visual Studio Code extensions often grow quickly in size. They are authored in multiple source files and depend on modules from [npm](https://www.npmjs.com). Decomposition and reuse are development best practices but they come at a cost when installing and running extensions. Loading 100 small files is much slower than loading one large file. That's why we recommend bundling. Bundling is the process of combining multiple small source files into a single file. + +For JavaScript, different bundlers are available. Popular ones are [rollup.js](https://rollupjs.org), [Parcel](https://parceljs.org), and [webpack](https://webpack.js.org/). This tutorial will focus on **webpack**, however, concepts and benefits of all bundlers are similar. + +## Using webpack + +Webpack is a development tool that's available from [npm](https://www.npmjs.com). To acquire webpack and its command-line interface, open the terminal and type: + +```bash +npm i --save-dev webpack webpack-cli +``` + +This will install webpack and update your extension's `package.json` file to include webpack in the `devDependencies`. Webpack is a JavaScript bundler but many VS Code extensions are written in TypeScript and only compiled to JavaScript. With the help of a loader `ts-loader`, webpack can understand TypeScript. Use the following to install `ts-loader`: + +```bash +npm i --save-dev ts-loader +``` + +## Configure webpack + +With all tools installed, webpack can now be configured. By convention, a `webpack.config.js` file contains the configuration to instruct webpack to bundle your extension. The sample configuration below is for VS Code extensions and should provide a good starting point: + +```javascript +//@ts-check + +'use strict'; + +const path = require('path'); + +/**@type {import('webpack').Configuration}*/ +const config = { + target: 'node', // vscode extensions run in a Node.js-context 📖 -> https://webpack.js.org/configuration/node/ + + entry: './src/extension.ts', // the entry point of this extension, 📖 -> https://webpack.js.org/configuration/entry-context/ + output: { // the bundle is stored in the 'dist' folder (check package.json), 📖 -> https://webpack.js.org/configuration/output/ + path: path.resolve(__dirname, 'dist'), + filename: 'extension.js', + libraryTarget: "commonjs2", + devtoolModuleFilenameTemplate: "../[resource-path]", + }, + devtool: 'source-map', + externals: { + vscode: "commonjs vscode" // the vscode-module is created on-the-fly and must be excluded. Add other modules that cannot be webpack'ed, 📖 -> https://webpack.js.org/configuration/externals/ + }, + resolve: { // support reading TypeScript and JavaScript files, 📖 -> https://github.com/TypeStrong/ts-loader + extensions: ['.ts', '.js'] + }, + module: { + rules: [{ + test: /\.ts$/, + exclude: /node_modules/, + use: [{ + loader: 'ts-loader', + }] + }] + }, +} +module.exports = config; +``` + +The file is [available](https://github.com/Microsoft/vscode-extension-samples/blob/master/webpack-sample/webpack.config.js) as part of the [webpack-extension](https://github.com/Microsoft/vscode-extension-samples/blob/master/webpack-sample) sample. Webpack configuration files are normal JavaScript modules that must export a configuration object. + +In the sample above, the following are defined: + +* The `target` is 'node' because extensions run in a Node.js context. +* The entry point webpack should use. This is similar to the `main` property in `package.json` except that you provide webpack with a "source" entry point, usually `src/extension.ts`, and not an "output" entry point. The webpack bundler understands TypeScript, so a separate TypeScript compile step is redundant. +* The `output` configuration tells webpack where to place the generated bundle file. By convention, that is the `dist` folder. In this sample, webpack will produce a `dist/extension.js` file. +* The `resolve` and `module/rules` configurations are there to support TypeScript and JavaScript input files. +* The `externals` configuration is used to declare exclusions, for example files and modules that should not be included in the bundle. The `vscode` module should not be bundled because it doesn't exist on disk but is created by VS Code on-the-fly when required. Depending on the node modules that an extension uses, more exclusion may be necessary. + +## Run webpack + +With the `webpack.config.js` file created, webpack can be invoked. You can run webpack from the command-line but to reduce repetition, using npm scripts is helpful. + +Merge these entries into the `scripts` section in `package.json`: + +```json +"scripts": { + "vscode:prepublish": "webpack --mode production", + "compile": "webpack --mode none", + "watch": "webpack --mode none --watch", +}, +``` + +The `compile` and `watch` scripts are for development and they produce the bundle file. The `vscode:prepublish` is used by `vsce`, the VS Code packaging and publishing tool, and run before publishing an extension. The difference is in the [mode](https://webpack.js.org/concepts/mode/) and that controls the level of optimization. Using `production` yields the smallest bundle but also takes longer, so `none` is used for development. To run above scripts, open a terminal and type `npm run compile` or select **Tasks: Run Task** from the Command Palette (`kb(workbench.action.showCommands)`). + +## Run the extension + +Before you can run the extension, the `main` property in `package.json` must point to the bundle, which for the configuration above is [`"./dist/extension"`](https://github.com/Microsoft/vscode-references-view/blob/d649d01d369e338bbe70c86e03f28269cbf87027/package.json#L26). With that change, the extension can now be executed and tested. For debugging configuration, make sure to update the `outFiles` property in the `launch.json` file. + +## Tests + +Extension authors often write unit tests for their extension source code. With the correct architectural layering, where the extension source code doesn't depend on tests, the webpack produced bundle shouldn't contain any test code. To run unit tests, only a simple compile is necessary. In the sample, there is a `test-compile` script, which uses the TypeScript compiler to compile the extension into the `out` folder. With that intermediate JavaScript available, the following snippet for `launch.json` is enough to run tests. + +```json +{ + "name": "Extension Tests", + "type": "extensionHost", + "request": "launch", + "runtimeExecutable": "${execPath}", + "args": [ + "--extensionDevelopmentPath=${workspaceFolder}", + "--extensionTestsPath=${workspaceFolder}/out/test" + ], + "outFiles": [ + "${workspaceFolder}/out/test/**/*.js" + ], + "preLaunchTask": "npm: test-compile" +} +``` + +This configuration for running tests is the same for non-webpacked extensions. There is no reason to webpack unit tests because they are not part of the published portion of an extension. + +## Publishing + +Before publishing, you should update the `.vscodeignore` file. Everything that's now bundled into the `dist/extension.js` file can be excluded, usually the `out` folder (in case you didn't delete it yet) and most importantly, the `node_modules` folder. + +A typical `.vscodeignore` file looks like this: + +```bash +.vscode +node_modules +out/ +src/ +tsconfig.json +webpack.config.json +``` + +## Migrate an existing extension + +Migrating an existing extension to use webpack is easy and similar to the getting started guide above. A real world sample that adopted webpack is the VS Code's References view through this [pull request](https://github.com/Microsoft/vscode-references-view/pull/50). + +There you can see: + +* Add `webpack`, `webpack-cli`, and `ts-loader` as `devDependencies`. +* Update npm scripts so that webpack is used for development. +* Update the debugger configuration `launch.json` file. +* Add and tweak the `webpack.config.js` configuration file. +* Update `.vscodeignore` to exclude `node_modules` and intermediate output files. +* Enjoy an extension that installs and loads much faster! + +## Troubleshooting + +### Minification + +Bundling in `production` mode also performs code minification. Minification compacts source code by removing whitespace and comments and by changing variable and function names into something ugly but short. Source code that uses `Function.prototype.name` works differently and so you might have to disable minification. + +### webpack critical dependencies + +When running webpack, you might encounter a warning like **Critical dependencies: the request of a dependency is an expression**. Such warnings must be taken seriously and likely your bundle won't work. The message means that webpack cannot statically determine how to bundle some dependency. This is usually caused by a dynamic `require` statement, for example `require(someDynamicVariable)`. + +To address the warning, you should either: + +* Try to make the dependency static so that it can be bundled. +* Exclude that dependency via the `externals` configuration. Also make sure that those JavaScript files aren't excluded from the packaged extension, using a negated glob pattern in `.vscodeignore`, for example `!node_modules/mySpecialModule`. + +## Next steps + +* [Extension Marketplace](/docs/editor/extension-gallery) - Learn more about VS Code's public extension Marketplace. +* [Testing Extensions](/api/working-with-extensions/testing-extension) - Add tests to your extension project to ensure high quality. +* [Continuous Integration](/api/working-with-extensions/continuous-integration) - Learn how to run extension CI builds on Azure Pipelines. diff --git a/api/working-with-extensions/continuous-integration.md b/api/working-with-extensions/continuous-integration.md new file mode 100644 index 0000000000000000000000000000000000000000..2fb50395af0ec842ce99ca5717211cf297b99c63 --- /dev/null +++ b/api/working-with-extensions/continuous-integration.md @@ -0,0 +1,117 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 891072bb-c46d-4392-800a-84d747072ce3 +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Use Continuous Integration for testing Visual Studio Code extensions (plug-ins). +--- + +# Continuous Integration + +Extension tests can be run on CI services. The `vscode` npm module provides a built-in command (`bin/test`) which: + +1. Downloads and unzips VS Code; +2. Launches your extension tests inside VS Code; +3. Prints the results to the console and exits with an appropriate status code. + +The command will expose some optional environment variables, which you can use to customize the build: + +| Name | Description | +| ------------------------- | ---------------------------------------------------------------------------------------------- | +| `CODE_VERSION` | Version of VS Code to run the tests against (e.g. `0.10.10`) | +| `CODE_DOWNLOAD_URL` | Full URL of a VS Code drop to use for running tests against | +| `CODE_TESTS_PATH` | Location of the tests to execute (default is `process.cwd()/out/test` or `process.cwd()/test`) | +| `CODE_EXTENSIONS_PATH` | Location of the extensions to load (default is `process.cwd()`) | +| `CODE_TESTS_WORKSPACE` | Location of a workspace to open for the test instance (default is CODE_TESTS_PATH) | +| `CODE_LOCALE` | Display language to use when running the tests (default is English) | +| `CODE_DISABLE_EXTENSIONS` | Disable all other extensions except the one that is being tested | +| `CODE_TESTS_DATA_DIR` | Allows to specify the user-data-dir for the tests to use and thus enables to run multiple tests at the same time | + +## Azure Pipelines + +Azure Pipelines + +You can create free projects on [Azure DevOps](https://azure.microsoft.com/services/devops/). This gives you source code hosting, planning boards, building and testing infrastructure, and more. On top of that, you get [10 free parallel jobs](https://azure.microsoft.com/services/devops/pipelines/) for building your projects across all 3 major platforms: Windows, macOS and Linux. + +After registering and creating your new project, simply add the following `build.yml` to the root of your extension's repository: + +```yaml +jobs: + - job: Windows + pool: + name: Hosted VS2017 + demands: npm + steps: + - task: NodeTool@0 + displayName: 'Use Node 8.x' + inputs: + versionSpec: 8.x + - task: Npm@1 + displayName: 'Install dependencies' + inputs: + verbose: false + - task: Npm@1 + displayName: 'Compile sources' + inputs: + command: custom + verbose: false + customCommand: 'run compile' + - script: 'node node_modules/vscode/bin/test' + displayName: 'Run tests' + - job: macOS + pool: + name: Hosted macOS + demands: npm + steps: + - task: NodeTool@0 + displayName: 'Use Node 8.x' + inputs: + versionSpec: 8.x + - task: Npm@1 + displayName: 'Install dependencies' + inputs: + verbose: false + - task: Npm@1 + displayName: 'Compile sources' + inputs: + command: custom + verbose: false + customCommand: 'run compile' + - script: 'node node_modules/vscode/bin/test' + displayName: 'Run tests' + - job: Linux + pool: + name: Hosted Ubuntu 1604 + demands: npm + steps: + - task: NodeTool@0 + displayName: 'Use Node 8.x' + inputs: + versionSpec: 8.x + - task: Npm@1 + displayName: 'Install dependencies' + inputs: + verbose: false + - task: Npm@1 + displayName: 'Compile sources' + inputs: + command: custom + verbose: false + customCommand: 'run compile' + - script: | + set -e + /usr/bin/Xvfb :10 -ac >> /tmp/Xvfb.out 2>&1 & + disown -ar + displayName: 'Start xvfb' + - script: 'node node_modules/vscode/bin/test' + displayName: 'Run tests' + env: + DISPLAY: :10 +``` + +Next [create a new Pipeline](https://docs.microsoft.com/azure/devops/pipelines/get-started-yaml?view=vsts#get-your-first-build) in your DevOps project and point it to the `build.yml` file. Trigger a build and voilà: + +![pipelines](images/continuous-integration/pipelines.png) + +You can enable the build to run continuously when pushing to a branch and even on pull requests. [Click here](https://docs.microsoft.com/azure/devops/pipelines/build/triggers) to learn more. diff --git a/api/working-with-extensions/images/continuous-integration/pipelines-logo.png b/api/working-with-extensions/images/continuous-integration/pipelines-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..5b7a94a3d58130ccff9ebe1c0f1234f3f90fbff2 Binary files /dev/null and b/api/working-with-extensions/images/continuous-integration/pipelines-logo.png differ diff --git a/api/working-with-extensions/images/continuous-integration/pipelines.png b/api/working-with-extensions/images/continuous-integration/pipelines.png new file mode 100644 index 0000000000000000000000000000000000000000..2c93615af258414d8b42c984def6e88be66748d0 --- /dev/null +++ b/api/working-with-extensions/images/continuous-integration/pipelines.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:90d57fdc3c207ebe424c3648ef6b6d514e8430b093d6a24b28c7e0c5ebe8da90 +size 150957 diff --git a/api/working-with-extensions/images/publishing-extension/token1.png b/api/working-with-extensions/images/publishing-extension/token1.png new file mode 100644 index 0000000000000000000000000000000000000000..c6be4a442077b5a3cd04d8f1150a8993fbab6a92 --- /dev/null +++ b/api/working-with-extensions/images/publishing-extension/token1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d9d209a2f0abc9eba6522891f4fb85b6cbdbe95e8d3140632963a1c9b7999cb8 +size 160064 diff --git a/api/working-with-extensions/images/publishing-extension/token2.png b/api/working-with-extensions/images/publishing-extension/token2.png new file mode 100644 index 0000000000000000000000000000000000000000..ba966ba30c2e468b551becb0354c6e23bd683c9a --- /dev/null +++ b/api/working-with-extensions/images/publishing-extension/token2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2ed3a1248116be4f5ac264b8f9d7fed4cb8ffc8baa7e0883e1e13c094d358893 +size 207120 diff --git a/api/working-with-extensions/images/publishing-extension/token3.png b/api/working-with-extensions/images/publishing-extension/token3.png new file mode 100644 index 0000000000000000000000000000000000000000..94fed3823e51e3a0008719bd98ca51f5932280e1 --- /dev/null +++ b/api/working-with-extensions/images/publishing-extension/token3.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ec5612a0e9514848327093c994e0ff79953d415726c7396079a30cfdf54ad348 +size 192787 diff --git a/api/working-with-extensions/images/publishing-extension/token4.png b/api/working-with-extensions/images/publishing-extension/token4.png new file mode 100644 index 0000000000000000000000000000000000000000..e02445be310621b948d0d7ebe61b5fa31663bd37 --- /dev/null +++ b/api/working-with-extensions/images/publishing-extension/token4.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b5bf0150f1a2b0ef9b56a57fe870ca8aabb32e1ca9e4057ac23d6f9596d9ab73 +size 192921 diff --git a/api/working-with-extensions/images/testing-extension/launch-tests.png b/api/working-with-extensions/images/testing-extension/launch-tests.png new file mode 100644 index 0000000000000000000000000000000000000000..c32a3f701e7e2328ae5c71f98aee9dc6f4a20a45 Binary files /dev/null and b/api/working-with-extensions/images/testing-extension/launch-tests.png differ diff --git a/api/working-with-extensions/images/testing-extension/pipelines-logo.png b/api/working-with-extensions/images/testing-extension/pipelines-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..ee1d649b4e723a149974a29ac099599c6b01e9c9 Binary files /dev/null and b/api/working-with-extensions/images/testing-extension/pipelines-logo.png differ diff --git a/api/working-with-extensions/images/testing-extension/pipelines.png b/api/working-with-extensions/images/testing-extension/pipelines.png new file mode 100644 index 0000000000000000000000000000000000000000..fa18d5e2353cce99ee4874b4208cb649b717b6cd --- /dev/null +++ b/api/working-with-extensions/images/testing-extension/pipelines.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:56ae4abd8cc6af8d755947227daf52f7d0a3bf2a8b75a36959f188d3397c2936 +size 286903 diff --git a/api/working-with-extensions/images/testing-extension/test-output.png b/api/working-with-extensions/images/testing-extension/test-output.png new file mode 100644 index 0000000000000000000000000000000000000000..41b72dc5d395d58f030935d26aa6f32c380459bc --- /dev/null +++ b/api/working-with-extensions/images/testing-extension/test-output.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f842aee46321d314c071340e4f794e34165cff790696f83ee0661381b64e18f8 +size 151411 diff --git a/api/working-with-extensions/profiling-extension.md b/api/working-with-extensions/profiling-extension.md new file mode 100644 index 0000000000000000000000000000000000000000..886582ca59fb5f1c5fd555eb65e6a3affc2a67a3 --- /dev/null +++ b/api/working-with-extensions/profiling-extension.md @@ -0,0 +1,6 @@ +--- +DateApproved: +MetaDescription: +--- + +# Profiling Extension diff --git a/api/working-with-extensions/publishing-extension.md b/api/working-with-extensions/publishing-extension.md new file mode 100644 index 0000000000000000000000000000000000000000..3ce692bfafdcfc20b7cb8f5a4f3e21d79701ec41 --- /dev/null +++ b/api/working-with-extensions/publishing-extension.md @@ -0,0 +1,255 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 7EA90618-43A3-4873-A9B5-61CC131CE4EE +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Learn how to publish Visual Studio Code extensions to the public Marketplace and share them with other developers. +--- + +# Publishing Extension + +Once you have made a high-quality extension, you can publish it to the [VS Code Extension MarketPlace](https://marketplace.visualstudio.com/vscode) so others could find, download and use your extension. Alternatively, you can [package](#packaging-extensions) an extension into the installable VSIX format and share it with other users. + +This topics covers: + +- Using [`vsce`](#vsce), the CLI tool for managing VS Code extensions +- [Packaging](#packaging-extensions), [publishing](#publishing-extensions) and [unpublishing](#unpublishing-extensions) extensions +- [Registering a `publisherId`](#create-a-publisher) necessary for publishing extensions + +## vsce + +[vsce](https://github.com/Microsoft/vsce), short for "Visual Studio Code Extensions", is a command line tool for packaging, publishing and managing VS Code extensions. + +### Installation + +Make sure you have [Node.js](https://nodejs.org/) installed. Then run: + +```bash +npm install -g vsce +``` + +### Usage + +You can use `vsce` to easily [package](#packaging-extensions) and [publish](#publishing-extensions) your extensions: + +```bash +$ cd myExtension +$ vsce package +# myExtension.vsix generated +$ vsce publish +# .myExtension published to VS Code MarketPlace +``` + +`vsce` can also search, get metadata of and unpublish extensions. For a reference on all the available `vsce` commands, run `vsce --help`. + +## Publishing extensions + +--- + +**Note:** Due to security concerns, `vsce` will not publish extensions which contain user provided SVG images. + +The publishing tool checks the following constraints: + +- The icon provided in `package.json` may not be an SVG. +- The badges provided in the `package.json` may not be SVGs unless they are from [trusted badge providers](/api/references/extension-manifest#approved-badges). +- Image URLs in `README.md` and `CHANGELOG.md` need to resolve to `https` URLs. +- Images in `README.md` and `CHANGELOG.md` may not be SVGs unless they are from [trusted badge providers](/api/references/extension-manifest#approved-badges). + +--- + +Visual Studio Code leverages [Azure DevOps](https://azure.microsoft.com/services/devops/) for its Marketplace services. This means that authentication, hosting, and management of extensions are provided through Azure DevOps. + +`vsce` can only publish extensions using [Personal Access Tokens](https://docs.microsoft.com/azure/devops/integrate/get-started/authentication/pats). You need to create at least one in order to publish an extension. + +### Get a Personal Access Token + +First, make sure you have an Azure DevOps [organization](https://docs.microsoft.com/azure/devops/organizations/accounts/create-organization-msa-or-work-student). + +In the following examples, the organization's name is `vscode`. From your organization's home page (for example: `https://dev.azure.com/vscode`), go to the **Security** page: + +![Security page](images/publishing-extension/token1.png) + +Select `Personal access tokens` and click **New Token** to create a new Personal Access Token: + +![Create personal access token](images/publishing-extension/token2.png) + +Give the Personal Access Token a name, optionally extend its expiration date to 1 year, make it accessible to every organization, select a **custom defined** scope ruleset and click **Show all scopes**: + +![Personal access token details](images/publishing-extension/token3.png) + +Finally, scroll down the list of possible scopes until you find **Marketplace** and select both **Acquire** and **Manage**: + +![Personal access token details](images/publishing-extension/token4.png) + +Click **Create** and you'll be presented with your newly created Personal Access Token. **Copy** it, you'll need it to create a publisher. + +### Create a publisher + +A **publisher** is an identity who can publish extensions to the Visual Studio Code Marketplace. Every extension needs to include a `publisher` name in its [`package.json` file](/api/references/extension-manifest). + +Once you have a [Personal Access Token](/api/working-with-extensions/publishing-extension#get-a-personal-access-token), you can create a new publisher using `vsce`: + +```bash +vsce create-publisher (publisher name) +``` + +`vsce` will remember the provided Personal Access Token for future references to this publisher. + +**Note:** Alternatively, create your publisher in the Marketplace publisher [management page](https://marketplace.visualstudio.com/manage) and login in `vsce`, as described in the next section. + +### Login to a publisher + +If you already created a publisher before and want to use it with `vsce`: + +```bash +vsce login (publisher name) +``` + +Similarly to the `create-publisher` command, `vsce` will ask you for the Personal Access Token and remember it for future commands. + +You can also enter your Personal Access Token as you publish with an optional parameter `-p `. + +```bash +vsce publish -p +``` + +## Auto-incrementing the extension version + +You can auto-increment an extension's version number when you publish by specifying the [SemVer](https://semver.org/) compatible number to increment: `major`, `minor`, or `patch`. + +For example, if you want to update an extension's version from 1.0.0 to 1.1.0, you would specify `minor`: + +```bash +vsce publish minor +``` + +This will modify the extension's `package.json` [version](/api/references/extension-manifest#fields) attribute before publishing the extension. + +You can also specify a complete SemVer compatible version on the command line: + +```bash +vsce publish 2.0.1 +``` + +## Unpublishing extensions + +You can unpublish an extension with the vsce tool by specifying the extension id `publisher.extension`. + +```bash +vsce unpublish (publisher name).(extension name) +``` + +> **Note:** When you unpublish an extension, the Marketplace will remove any extension statistics it has collected. You may want to update your extension rather than unpublish it. + +## Packaging extensions + +If you want to test an extension on your local install of VS Code or distribute an extension without publishing it to VS Code MarketPlace, you can choose to package your extension. `vsce` can package your extension into a `VSIX` file, from which users can easily install. Some extensions publish VSIX files to each GitHub release. + +For extension authors, they can run `vsce package` in extension root folder to create such VSIX files. + +For users who receive such a VSIX file, they can install the extension with `code --install-extension my-extension-0.0.1.vsix`. + +### Sharing privately with others + +If you want to share your extension with others privately, you can send them your packaged extension `.vsix` file. + +## Your extension folder + +To load an extension, you need to copy the files to your VS Code extensions folder `.vscode/extensions`. Depending on your platform, it is located in the following folders: + +- **Windows** `%USERPROFILE%\.vscode\extensions` +- **macOS** `~/.vscode/extensions` +- **Linux** `~/.vscode/extensions` + +## Visual Studio Code compatibility + +When authoring an extension, you will need to describe what is the extension's compatibility to Visual Studio Code itself. This can done via the `engines.vscode` field inside `package.json`: + +```json +{ + "engines": { + "vscode": "^1.8.0" + } +} +``` + +A value of `1.8.0` means that your extension is compatible only with VS Code `1.8.0`. A value of `^1.8.0` means that your extension is compatible with VS Code `1.8.0` and onwards, including `1.8.1`, `1.9.0`, etc. + +You can use the `engines.vscode` field to make sure the extension only gets installed for clients which contain the API you depend on. This mechanism plays well with the Stable release as well as the Insiders one. + +For example, imagine that the latest Stable version of VS Code is `1.8.0` and that during `1.9.0`'s development a new API is introduced and thus made available in the Insider release through version `1.9.0-insider`. If you want to publish an extension version which benefits from this API, you should indicate a version dependency of `^1.9.0`. Your new extension version will be installed only on VS Code `>=1.9.0`, which means all current Insider customers will get it, while the Stable ones will only get the update when Stable reaches `1.9.0`. + +## Advanced usage + +### Marketplace integration + +You can customize how your extension looks in the Visual Studio Marketplace. See the [Go extension](https://marketplace.visualstudio.com/items/ms-vscode.Go) for an example. + +Here are some tips for making your extension look great on the Marketplace: + +- A `README.md` file at the root of your extension will be used to populate the extension's Marketplace page's contents. `vsce` will modify README links for you in two different ways: + - If you add a `repository` field to your `package.json` and if it is a public GitHub repository, `vsce` will automatically detect it and adjust the links accordingly. + - You can override that behavior and/or set it by using the `--baseContentUrl` and `--baseImagesUrl` flags when running `vsce package`. Then publish the extension by passing the path to the packaged `.vsix` file as an argument to `vsce publish`. +- A `LICENSE` file at the root of your extension will be used as the contents for the extension's license. +- A `CHANGELOG.md` file at the root of your extension will be used as the contents for the extension's change log. +- You can set the banner background color by setting `galleryBanner.color` to the intended hex value in `package.json`. +- You can set an icon by setting `icon` to a relative path to a squared `128px` PNG file included in your extension, in `package.json`. + +Also see [Marketplace Presentation Tips](/api/references/extension-manifest#marketplace-presentation-tips). + +### `.vscodeignore` + +You can create a `.vscodeignore` file to exclude some files from being included in your extension's package. This file is a collection of [glob](https://github.com/isaacs/minimatch) patterns, one per line. + +For example: + +```bash +**/*.ts +**/tsconfig.json +!file.ts +``` + +You should ignore all files not needed at runtime. For example, if your extension is written in TypeScript, you should ignore all `**/*.ts` files, like in the previous example. + +**Note:** Development dependencies listed in `devDependencies` will be automatically ignored, you don't need to add them to the `.vscodeignore` file. + +### Pre-publish step + +It's possible to add a pre-publish step to your manifest file. The command will be called every time the extension is packaged. + +```json +{ + "name": "uuid", + "version": "0.0.1", + "publisher": "joaomoreno", + "engines": { + "vscode": "0.10.x" + }, + "scripts": { + "vscode:prepublish": "tsc" + } +} +``` + +This will always invoke the [TypeScript](https://www.typescriptlang.org/) compiler whenever the extension is packaged. + +## Next steps + +* [Extension Marketplace](/docs/editor/extension-gallery) - Learn more about VS Code's public extension Marketplace. +* [Testing Extensions](/api/working-with-extensions/testing-extension) - Add tests to your extension project to ensure high quality. +* [Bundling Extensions](/api/working-with-extensions/bundling-extension) - Improve load times by bundling your extension files with webpack. + +## Common questions + +### I get 403 Forbidden (or 401 Unauthorized) error when I try to publish my extension? + +One easy mistake to make when creating the PAT (Personal Access Token) is to not select `all accessible accounts` in the Accounts field drop-down (instead selecting a specific account). You should also set the Authorized Scopes to `All scopes` for the publish to work. + +### I can't unpublish my extension through the `vsce` tool? + +You may have changed your extension ID or publisher name. You can also manage your extensions directly on the Marketplace by going to the [manage page](https://marketplace.visualstudio.com/manage). You can update or unpublish your extension from your publisher manage page. + +### Why does vsce not preserve file attributes? + +Please note that when building and publishing your extension from Windows, all the files included in the extension package will lack POSIX file attributes, namely the executable bit. Some `node_modules` dependencies rely on those attributes to properly function. Publishing from Linux and macOS works as expected. diff --git a/api/working-with-extensions/testing-extension.md b/api/working-with-extensions/testing-extension.md new file mode 100644 index 0000000000000000000000000000000000000000..ddbc0d21bdb5f09a614873b453edd9dfd2a208f0 --- /dev/null +++ b/api/working-with-extensions/testing-extension.md @@ -0,0 +1,97 @@ +--- +# DO NOT TOUCH — Managed by doc writer +ContentId: 2447F8EB-15F1-4279-B621-126C7B8EBF4B +DateApproved: 3/7/2019 + +# Summarize the whole topic in less than 300 characters for SEO purpose +MetaDescription: Write tests for your Visual Studio Code extension (plug-in). +--- + +# Testing Extension + +Visual Studio Code supports running and debugging tests for your extension. These tests will run inside a special instance of VS Code named the `Extension Development Host`, and have full access to the VS Code API. We refer to these tests as integration tests, because they go beyond unit tests that can run without a VS Code instance. This documentation focuses on VS Code integration tests. For unit testing, you can use any popular testing framework, like [Mocha](https://mochajs.org/) or [Jasmine](https://jasmine.github.io/). + +## Yo Code test scaffolding + +If you are using the [yo code generator](https://github.com/Microsoft/vscode-generator-code), the generated projects include a sample test and instructions for running the tests. + +**Note**: The documentation below assumes that you created a TypeScript extension but the same also applies for a JavaScript extension. However, some file names may be different. + +After you've created a new extension and opened the project in VS Code, you can select the `Extension Tests` configuration from the drop-down at the top of the Debug View. + +![launch tests](images/testing-extension/launch-tests.png) + +With this configuration chosen, when you run `Debug: Start` (`kb(workbench.action.debug.start)`), VS Code launches your extension in the `Extension Development Host` instance and runs your tests. Test output goes to the Debug Console where you can see the test results. + +![test output](images/testing-extension/test-output.png) + +The generated test uses the [Mocha test framework](https://mochajs.org/) for its test runner and library. + +The extension project comes with a `src/test` folder that includes an `index.ts` file which defines the Mocha test runner configuration and an `extension.test.ts` which has the example `Something 1` test. You can typically leave `index.ts` untouched, but you can modify it to adjust the configuration of Mocha. + +``` +├── src +│ └── test +│ ├── extension.test.ts +│ └── index.ts +``` + +You can create more `test.ts` files under the `test` folder and they will automatically be built (to `out/test`) and run. The test runner will only consider files matching the name pattern `*.test.ts`. + +## Launch tests configuration + +The `Extension Tests` configuration is defined in the project's `.vscode\launch.json` file. It is similar the `Extension` configuration with the addition of the `--extensionTestsPath` argument which points to the compiled test files (assuming this is a TypeScript project). + +```json +{ + "name": "Extension Tests", + "type": "extensionHost", + "request": "launch", + "runtimeExecutable": "${execPath}", + "args": [ + "--extensionDevelopmentPath=${workspaceFolder}", + "--extensionTestsPath=${workspaceFolder}/out/test" + ], + "outFiles": ["${workspaceFolder}/out/test/**/*.js"] +} +``` + +## Passing arguments to the Extension Development Host + +You can set the file or folder that the test instance should open by inserting the path at the front of the argument list for the launch configuration. + +```json +"args": [ + "${workspaceFolder}/file or folder name", + "--extensionDevelopmentPath=${workspaceFolder}", + "--extensionTestsPath=${workspaceFolder}/out/test" +] +``` + +This way you can run your tests with predictable content and folder structure. + +## Disabling other extensions + +By default, the debug instance of VS Code will load any extension you've previously installed alongside the one you are developing. If you want to disable those extensions, add `"--disable-extensions"` to the argument list in the launch configuration. + +```json +"args": [ + "--disable-extensions", + "--extensionDevelopmentPath=${workspaceFolder}", + "--extensionTestsPath=${workspaceFolder}/out/test" +] +``` + +This will give large benefits to performance when running tests + +## Excluding test files from your extension package + +If you decide to share your extension, you may not want to include the tests in your extension package. The [`.vscodeignore`](/api/working-with-extensions/publishing-extension#advance-usage) file lets you exclude test files when you package and publish your extension with the [`vsce` publishing tool](/api/working-with-extensions/publishing-extension). By default, the `yo code` generated extension project excludes the `test` and `out/test` folders. + +``` +out/test/** +``` + +## Next steps + +- [Continuous Integration](/api/working-with-extensions/continuous-integration) - Run your extension tests in a Continuous Integration service such as Azure DevOps. diff --git a/blogs/2016/02/01/insiders_build_icon.png b/blogs/2016/02/01/insiders_build_icon.png new file mode 100644 index 0000000000000000000000000000000000000000..955e1dc2da615aa6dce1162b56a7ae02550ad516 Binary files /dev/null and b/blogs/2016/02/01/insiders_build_icon.png differ diff --git a/blogs/2016/02/01/introducing_insiders_build.md b/blogs/2016/02/01/introducing_insiders_build.md new file mode 100644 index 0000000000000000000000000000000000000000..48941db3178e4d132ac8c60caab552f93b38476b --- /dev/null +++ b/blogs/2016/02/01/introducing_insiders_build.md @@ -0,0 +1,38 @@ +--- +Order: +TOCTitle: The Insiders Build +PageTitle: Introducing the Insiders Build +MetaDescription: insiders build +MetaSocialImage: /assets/blogs/2016/02/01/opengraph_insiders.png +Date: 2016-02-01 +ShortDescription: VS Code has its roots in the web (built using TypeScript and Node.js) and one thing we love about cloud based applications is that they are always up to date. Update the service and all of your users are instantly on the latest fixes and features, with no user interaction. +Author: Chris Dias +--- + +# Introducing the Insiders Build + +February 1, 2016 by Chris Dias, [@chrisdias](https://twitter.com/chrisdias) + +VS Code has its roots in the web (built using TypeScript and Node.js) and one thing we love about cloud based applications is that they are always up to date. Update the service and all of your users are instantly on the latest fixes and features, with no user interaction. + +This is why VS Code has automatic updates on by default. We periodically query the update service to see if a new version is available, download it when ready, and then gently prompt you to restart. + +Of course, it has always been possible to turn off automatic updates. It has also always been possible to subscribe to what we called the “Insiders Channel” which gave you get early access to monthly drops, letting you check out new features, test an extension, or even help us find that last-minute show stopper issue. + +There were two shortcomings to this model. First, you needed to join the “Insiders Program” to learn about the “updateChannel”: “insiders” setting. Second, you had to choose whether you want to work with the Stable (the official monthly release) or the Insiders version. You could not easily switch back to Stable if you hit a blocking issue with the Insiders drop, without having to change settings. + +With the open sourcing of VS Code in November, we are retiring the Insiders Program. With the upcoming January 2016 release, we are introducing a new Insiders build that installs side by side with the monthly, stable VS Code release. + +![Insiders and Stable, side by side, don't worry, the green icon is temporary](insiders_build_icon.png) + +No longer do you need to manage settings to switch between the two. The Insiders build is a separate installation with isolated settings, extensions, and configurations. This does mean that you will need to configure both and install your favorite extensions into each, but once you’ve done this, trying out new features (and giving us feedback!) is easier than ever. + +The Insiders build will automatically update when we release new builds, generally towards the end of each month. Depending on how successful this process is we will consider releasing new updates even more often. + +The features included in the Insiders build is tracked in [our iteration plans](https://github.com/Microsoft/vscode/issues?utf8=%E2%9C%93&q=label%3Aiteration-plan+). Feel free to communicate your thoughts, ideas and bug reports on these builds – we will be paying close attention to the feedback as it helps us stabilize before an official release. + +[Download the Insiders build](/insiders) today! Again, you only need to install it once and it will update itself when we push new builds each month. + +Note: If you have been an “Insider”, you will need to manually download this new drop to keep testing the latest and greatest of VS Code. Your current build will upgrade to the latest stable release when we ship at the end of the month. + +Chris Dias \ No newline at end of file diff --git a/blogs/2016/02/01/opengraph_insiders.png b/blogs/2016/02/01/opengraph_insiders.png new file mode 100644 index 0000000000000000000000000000000000000000..42b3b4886d81d05b96b0a1c6c6666c70f151f759 Binary files /dev/null and b/blogs/2016/02/01/opengraph_insiders.png differ diff --git a/blogs/2016/02/23/chrome-debugger-demo.gif b/blogs/2016/02/23/chrome-debugger-demo.gif new file mode 100644 index 0000000000000000000000000000000000000000..ac1d3938c57f0ece1c6884416da7c849c670b384 --- /dev/null +++ b/blogs/2016/02/23/chrome-debugger-demo.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d35302f9cd9abd97faec20202c2bd6ae8b3afebad088e0d5ce4d000a76a1dd08 +size 6506421 diff --git a/blogs/2016/02/23/introducing-chrome-debugger-for-vs-code.md b/blogs/2016/02/23/introducing-chrome-debugger-for-vs-code.md new file mode 100644 index 0000000000000000000000000000000000000000..f54a9c340f5fc0b37299e2d059a5a81605fddc2a --- /dev/null +++ b/blogs/2016/02/23/introducing-chrome-debugger-for-vs-code.md @@ -0,0 +1,64 @@ +--- +Order: +TOCTitle: Introducing Chrome Debugging +PageTitle: Introducing Chrome Debugging for VS Code +MetaDescription: Chrome debugger extension for Visual Studio Code +Date: 2016-02-23 +ShortDescription: Since the first release of Visual Studio Code, one of our focuses has been to simplify the daily workflow for developers by enabling them to debug their code directly from the editor. We started out with .NET and Node.js debugging, and today we are taking the next step by introducing our Chrome Debugger for Visual Studio Code. +Author: Andy Sterland +--- + +# Introducing Chrome Debugging for VS Code + +February 23, 2016 by [Andy Sterland](https://twitter.com/AndySterland) and [Kenneth Auchenberg](https://twitter.com/auchenberg) + +Since the first release of Visual Studio Code, one of our focuses has been to simplify the daily workflow for developers by enabling them to debug their code directly from the editor. We started out with .NET and Node.js debugging, and today we are taking the next step by introducing our Chrome Debugger for Visual Studio Code. + +Our Chrome Debugger allows front-end developers to debug their client-side JavaScript code running inside Google Chrome directly from Visual Studio Code. + +
+ +![Demo](chrome-debugger-demo.gif) + +## How does it work? + +Our debugger works by connecting to Chrome over its [Chrome Debugger protocol](https://developer.chrome.com/devtools/docs/debugger-protocol), where we map files loaded in the browser to the files open in Visual Studio Code. This means developers now can set breakpoints directly in their source code, set up variables to watch and see the full call stack when debugging — all without leaving the editor. + +In the above example, we are showing an [AngularJS](https://github.com/auchenberg/timey) app bundled and minified via [Browserify](http://browserify.org/) being debugged from VS Code. This works because our debugger understands [JavaScript Source Maps](https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/), which we’ll use to enable developers to debug straight from their original source, and not the transpiled result that the browser sees. Supporting source maps also enables debugging of [TypeScript](https://www.typescriptlang.org/) straight from VS Code. + +For now, Chrome needs to be started with remote debugging enabled, and only supports one concurrent connection. This means if you open up DevTools inside Chrome, the connection to VS Code will get terminated by Chrome. This is slightly annoying, and we hope this [issue](https://bugs.chromium.org/p/chromium/issues/detail?id=129539) will be fixed sometime soon. + +## To get started + +To get started, open the **Extensions** view (`kb(workbench.view.extensions)`). When the extension list appears, type 'chrome' to filter the list and install the `Debugger for Chrome` extension. You'll then create a launch-configuration file which we explain in detail in our README [right here](https://github.com/Microsoft/vscode-chrome-debug). + +You can either setup VS Code to connect to an already running Chrome instance or simply start a new one with remote debugging enabled, but read more about that in our [README](https://github.com/Microsoft/vscode-chrome-debug). + +## Supported features + +In this first release, we support the following features: + +- Setting breakpoints, including within source files when source maps are enabled +- TypeScript, via source maps +- Stepping, including using the buttons on the Chrome page +- Locals scope variables via the VS Code Locals pane +- Debugging eval scripts, script tags, and scripts that are added dynamically +- Watches via the VS Code Watch panel. +- The debug console +- Most console APIs + +## Going forward + +We believe there’s much to be done for front-end developers, as building for the web in the recent years has become incredibly complex. With our Chrome debugger, we are taking the first step towards a simpler web development workflow, where browsers and tooling from different vendors are able to work together, and building for the web feels more integrated. + +We’ve released this extension on [GitHub](https://github.com/Microsoft/vscode-chrome-debug) as an MIT licensed open source project. It’s a work in progress, so see our issues page for known bugs – for example, we have a few issues around supporting all flavors of generated source maps. + +For now we support Google Chrome, but we’re also looking at expanding our support to [Microsoft Edge](https://www.microsoft.com/en-us/windows/microsoft-edge) and other browsers. We really want your feedback and help to build an even better debugging experience. + +If you have any issues or ideas for improvements, feel free to reach out to us on [Twitter](https://twitter.com/code) or [GitHub](https://github.com/Microsoft/vscode-chrome-debug/). + +– + +[Andy Sterland](https://twitter.com/AndySterland), Senior Program Manager, JavaScript Diagnostics
+[Kenneth Auchenberg](https://twitter.com/auchenberg), Program Manager, JavaScript Diagnostics + diff --git a/blogs/2016/03/07/Feb2016Release.md b/blogs/2016/03/07/Feb2016Release.md new file mode 100644 index 0000000000000000000000000000000000000000..74de91136af05094f18c18c690fdbf1fbbae9749 --- /dev/null +++ b/blogs/2016/03/07/Feb2016Release.md @@ -0,0 +1,28 @@ +--- +Order: +TOCTitle: February 2016 Release +PageTitle: Visual Studio February 2016 Release +MetaDescription: Announcing the Visual Studio Code February 2016 Release +Date: 2016-03-07 +ShortDescription: Announcing the February 2016 Release of VS Code +Author: Chris Dias +--- + +# February 2016 Release + +March 7, 2016 by The VS Code Team, [@code](https://twitter.com/code) + +Today we are releasing the February 2016 build of Visual Studio Code. This release brings many improvements to your development experience, including: + +* **JavaScript**: [Salsa](https://github.com/Microsoft/TypeScript/issues/4789) is now the default JavaScript/TypeScript language service, bringing support for React and React Native to VS Code. +* **Code Folding**: The most requested feature in [UserVoice](https://visualstudio.uservoice.com/forums/293070-visual-studio-code/suggestions/7752321-add-code-folding-support) is now on by default. +* **Extensions**: VS Code can make recommendations for extensions based on the files you've opened in the tool (Press `kb(workbench.action.showCommands)`, search for "recommend"). +* **Accessibility**: Screen reader support in the Editor is now on by default. + +And much, much more. Please see our [Release Notes](https://go.microsoft.com/fwlink/?LinkID=533483) for more information. + +If you have automatic updates turned on (OS X and Windows) then you'll get prompted soon. Otherwise, [download VS Code today](https://code.visualstudio.com)! + +Happy Coding!! + +The VS Code Team diff --git a/blogs/2016/03/11/ExtensionsRoundup.md b/blogs/2016/03/11/ExtensionsRoundup.md new file mode 100644 index 0000000000000000000000000000000000000000..1d84cf9674d5e2e076f5b989155c657584739b2b --- /dev/null +++ b/blogs/2016/03/11/ExtensionsRoundup.md @@ -0,0 +1,77 @@ +--- +Order: +TOCTitle: Extensions Roundup +PageTitle: Visual Studio Code Extensions Roundup +MetaDescription: New, useful, and interesting extensions in Visual Studio Code. +Date: 2016-03-17 +ShortDescription: New, useful, and interesting extensions in Visual Studio Code. +Author: Wade Anderson +--- + +# VS Code Extensions + +March 17, 2016 by Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +In November 2015, we open sourced Visual Studio Code and introduced the [extensions API](https://code.visualstudio.com/docs/extensionAPI/vscode-api). The VS Code extensions [Marketplace](https://marketplace.visualstudio.com/VSCode) has over 850 extensions. Many new languages (Go, PowerShell, PHP, Python) and frameworks (Apache Cordova, React Native) are now supported. + +We will continue to iterate on improving the API and we would love your [feedback](https://github.com/Microsoft/vscode/issues). If you are new to VS Code extensions, check out the [docs](https://code.visualstudio.com/docs/editor/extension-gallery) for instructions on finding and installing new extensions. We are invested in empowering the community to make VS Code the world's greatest code editor. + +In the spirit of a great [curated extensions list](https://github.com/viatsko/awesome-vscode), we wanted to give you regular updates on what is happening in the VS Code extensions [Marketplace](https://marketplace.visualstudio.com/VSCode). + +## Ruby by Peng Lv + +Ruby language support is a popular request on [UserVoice](https://visualstudio.uservoice.com/forums/293070-visual-studio-code?query=ruby), with a handful of extensions +in the [Marketplace](https://marketplace.visualstudio.com/search?term=ruby&target=VSCode&sortBy=UpdatedDate). We've enjoyed playing with this [Ruby extension](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby) that provides language and debugging support. The setup is simple and is contained in the extension's [README](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby). + +### Install Ruby Dependencies + +Here are the instructions for various Ruby versions. I am using Ruby v2.0.x. + +1. In the terminal, type `gem install ruby-debug-ide -v 0.4.32`. +2. In the terminal, type `gem install debase -v 0.2.1`. + +### Configure Launch.json in VS Code + +Create a `launch.json` file in `.vscode` folder and add the following: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Ruby Debug", + "type": "Ruby", + "request": "launch", + "program": "${workspaceFolder}/hello_world.rb", + "stopOnEntry": false + } + ] +} +``` + +### Write Code and Debug + +Below is an example session debugging a simple Hello World Ruby script. You can see setting a breakpoint, starting the debugger, hitting the breakpoint, and single stepping through the code. + +![Ruby Debugging](ruby_debugging.gif) + +## yo by Sam Verschueren + +This extension lets you use the Yeoman scaffolding tool from within VS Code in the Command Palette. Your installed Yeoman generators are displayed in a drop down and you answer the Yeoman terminal prompts right from within VS Code. [See more details at the Marketplace](https://marketplace.visualstudio.com/items?itemName=samverschueren.yo). + +![Yo Demo](yo_demo.gif) + +## change-case by wmaurer + +Change the case of the currently selected word or selection. This [extension](https://marketplace.visualstudio.com/items?itemName=wmaurer.change-case) is implemented as a wrapper around the [node-change-case](https://github.com/blakeembrey/node-change-case) npm module. + +![change-case demo](change-case_demo.gif) + +## Subscribe + +Subscribe to the VS Code [RSS feed](feed.xml) to get more updates on extensions. + +And if you have an extension you really like and want to see it featured here, send us a [Tweet](https://twitter.com/code). + +Wade Anderson, VS Code Team Member
+[@waderyan_](https://twitter.com/waderyan_) diff --git a/blogs/2016/03/11/change-case_demo.gif b/blogs/2016/03/11/change-case_demo.gif new file mode 100644 index 0000000000000000000000000000000000000000..424633df0d5fb9637ee3ec0e5ef15a20fc598013 --- /dev/null +++ b/blogs/2016/03/11/change-case_demo.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b9df54ee26a1e55c552856d023fad8c5d8d6153ad6735385aba15e621de4d31a +size 172289 diff --git a/blogs/2016/03/11/ruby_debugging.gif b/blogs/2016/03/11/ruby_debugging.gif new file mode 100644 index 0000000000000000000000000000000000000000..b26528e135ba36594346c5902c549e173916da57 --- /dev/null +++ b/blogs/2016/03/11/ruby_debugging.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:73751be8caa8ee5bfdff679132a62d41a3760ff13967a1e8e32e4e4cc3cd7acb +size 362064 diff --git a/blogs/2016/03/11/yo_demo.gif b/blogs/2016/03/11/yo_demo.gif new file mode 100644 index 0000000000000000000000000000000000000000..2a15febe6b18f3fe5e3f391c002911c3c437eaa8 --- /dev/null +++ b/blogs/2016/03/11/yo_demo.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2acc5b22b51621fb12815743f7d0340a4939c817c6814caa7678f35e4964594b +size 127414 diff --git a/blogs/2016/03/14/Feb2016Recovery.md b/blogs/2016/03/14/Feb2016Recovery.md new file mode 100644 index 0000000000000000000000000000000000000000..d2659e487b91063640fd17787fd2d326d18b3eb5 --- /dev/null +++ b/blogs/2016/03/14/Feb2016Recovery.md @@ -0,0 +1,26 @@ +--- +Order: +TOCTitle: February 2016 Recovery Release +PageTitle: Visual Studio Code February 2016 Recovery Release +MetaDescription: Visual Studio Code February 2016 Recovery Release +Date: 2016-03-14 +ShortDescription: The February 2016 Recovery Release of VS Code +Author: Chris Dias +--- + +# February 2016 "Recovery" Release + +March 14, 2016 by The VS Code Team, [@code](https://twitter.com/code) + +If we find critical issues after a major update, we do what we call a "recovery" release. Today we're updating the February 2016 build with fixes for the following four issues: + +- [3903](https://github.com/Microsoft/vscode/issues/3903): [js] syntax highlight for 'var' and 'function' not working in Default VS theme +- [3899](https://github.com/Microsoft/vscode/issues/3899): [folding] sections are still folded when disabled in preferences +- [3509](https://github.com/Microsoft/vscode/issues/3509): Smoke Test: Don't get cross file IntelliSense in JS +- [3894](https://github.com/Microsoft/vscode/issues/3894): [Handlebars] Curly braces edit issues + +The latest version is now `0.10.11` and if you have automatic updates turned on (OS X and Windows), you'll soon be prompted to install. Otherwise, please [download now](https://code.visualstudio.com). + +Thanks to everyone who submitted these issues. + +The VS Code Team \ No newline at end of file diff --git a/blogs/2016/04/04/vscode-at-build.md b/blogs/2016/04/04/vscode-at-build.md new file mode 100644 index 0000000000000000000000000000000000000000..48e22a8739f8243d6af25bee0e8c9fbcd35c4ef9 --- /dev/null +++ b/blogs/2016/04/04/vscode-at-build.md @@ -0,0 +1,47 @@ +--- +Order: +TOCTitle: VS Code at //build/ +PageTitle: Visual Studio Code at Build 2016 +MetaDescription: Visual Studio Code at Build 2016. Learn about presentations featuring VS Code. +Date: 2016-04-05 +ShortDescription: Visual Studio Code had a great presence at Build 2016. +Author: Wade Anderson +--- + +# VS Code at //build/ + +April 5, 2016 by Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +This year's [Build 2016 conference](https://build.microsoft.com/) in San Francisco was very exciting and Visual Studio Code was happy to be a part of it. VS Code featured prominently as the editor of choice in many talks and demos and there were several presentations dedicated to VS Code. + +## Tips and Tricks + +Don't miss this well attended session on [Best of VS Code: Tips and Tricks](https://channel9.msdn.com/Events/Build/2016/B887). You'll start by learning the basics of VS Code and quickly become a power user through useful [Tips and Tricks](https://github.com/Microsoft/vscode-tips-and-tricks). The talk finishes with a working "To Do" list [sample](https://github.com/Microsoft/vscode-react-sample) written in JavaScript, Node.js and React/JSX. + +## What's New in TypeScript + +TypeScript architect Anders Hejlsberg's talk on [What's New in TypeScript?](https://channel9.msdn.com/Events/Build/2016/B881) used VS Code throughout his demos. This talk is also a great way to understand the TypeScript/JavaScript improvements in VS Code when we adopted the new TypeScript language service, codename "Salsa". + +## The Future of C# + +There's a nice section on VS Code integration and C# debugging later in [The Future of C#](https://channel9.msdn.com/Events/Build/2016/B889) starting at minute 39 (but you'll want to watch the entire entertaining talk). + +## Node.js and Microsoft + +As you'd expect from a talk called [Node.js and Microsoft: A Love Story about Developer Tools](https://channel9.msdn.com/Events/Build/2016/B870), VS Code is going to be starring. Check out the sections on using `nodemon` to automatically reattach the VS Code Node.js debugger (minute 28) and the cool prototype of time travel debugging (minute 39). + +## Channel 9 + +[Channel 9's coverage of //build/ 2016](https://channel9.msdn.com/Events/Build/2016) is a great resource to learn more about VS Code and technologies like Cordova, Ionic, Angular, and React Native where VS Code is a good match for a high performance editor. Browse or search for your area of interest and we're sure you'll find a relevant presentation or panel discussion. + +## New Extensions + +There were also several new VS Code extensions released at //build/: + +* [C/C++ for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) - Complete C/C++ language support including code-editing and debugging. See a demo in [C++ Discussion](https://channel9.msdn.com/Events/Build/2016/C-Discussion). +* [NativeScript](https://marketplace.visualstudio.com/items?itemName=Telerik.nativescript) - NativeScript support for Visual Studio Code. + +Visit the VS Code [Extensions Marketplace](https://marketplace.visualstudio.com/VSCode) to learn more about these and other useful extensions. + +Wade Anderson, VS Code Team Member
+[@waderyan_](https://twitter.com/waderyan_) diff --git a/blogs/2016/04/14/header.png b/blogs/2016/04/14/header.png new file mode 100644 index 0000000000000000000000000000000000000000..7f3a0a5c54ec746fa049803fdd27339671bc1dc0 --- /dev/null +++ b/blogs/2016/04/14/header.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ff831e61d96fb3bae37dd0a7b0f4e989906c2945f37bc37490b4080fd0f8e2c4 +size 125608 diff --git a/blogs/2016/04/14/installs.png b/blogs/2016/04/14/installs.png new file mode 100644 index 0000000000000000000000000000000000000000..4db3a54bf7672ba9af487875d4c6c874b674d005 --- /dev/null +++ b/blogs/2016/04/14/installs.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:388289a60e7424ee6c765369763d7e33d6581a93246aee7f6603edf7f08219fc +size 118404 diff --git a/blogs/2016/04/14/timeline.png b/blogs/2016/04/14/timeline.png new file mode 100644 index 0000000000000000000000000000000000000000..17bbfb2855db97da6dd5cca7963b2cbfbe407252 Binary files /dev/null and b/blogs/2016/04/14/timeline.png differ diff --git a/blogs/2016/04/14/vscode-1.0.md b/blogs/2016/04/14/vscode-1.0.md new file mode 100644 index 0000000000000000000000000000000000000000..9ebb2ba5dd2438ae7e741925a096e36ffa254bfe --- /dev/null +++ b/blogs/2016/04/14/vscode-1.0.md @@ -0,0 +1,83 @@ +--- +Order: +TOCTitle: 1.0 Release +PageTitle: Visual Studio Code 1.0 Release +MetaDescription: Visual Studio Code releases 1.0. +Date: 2016-04-14 +ShortDescription: Visual Studio Code releases 1.0. +Author: PJ Meyer +MetaSocialImage: /assets/blogs/2016/04/14/header.png +--- + +# Visual Studio Code 1.0! + +April 14, 2016 by The VS Code Team, [@code](https://twitter.com/code) + +![header graphic](header.png) + +Today we’re very proud to release version 1.0 of Visual Studio Code. Since our initial launch one year ago, 2 million developers have installed VS Code. Today, we’re excited to report that more than 500,000 developers actively use VS Code each month. + +What started as an experiment to build a production quality editor using modern web technologies has blossomed into a new kind of cross-platform development tool, one that focuses on core developer productivity by centering the product on rich code editing and debugging experiences. Visual Studio Code brings the industry-leading experiences of Visual Studio to a streamlined development workflow, that can be a core part of the tool set of every developer, building any kind of application. + +Getting to "1.0" over the last few months has been about more than features. We have worked with the community to further improve stability, fixing hundreds of bugs. And we’ve pushed hard on getting the best performance we can out of the editing experience. + +VS Code was initially built for developers creating web apps using JavaScript and TypeScript. But in less than 6 months since we made the product extensible, the community has built over [1000 extensions](https://marketplace.visualstudio.com/vscode) that now provide support for almost any language or runtime in VS Code. Today, a broad range of developers from individuals and startups to Fortune 500 companies, including audiences completely new to Microsoft’s tools, are all more productive with a tool that fits comfortably into their current tool chain and workflow, and supports the technologies they use, from Go and Python to React Native and C++. With this great ecosystem in place, we’re now confident in declaring our API as stable, and guaranteeing compatibility going forward. + +And we have strived to make VS Code 1.0 a great editor for every developer. VS Code is now fully localizable, and ships in 9 different languages, including French, German, Japanese, and Chinese. And, we have worked to make VS Code the most accessible of modern editors, with full keyboard navigation and support for screen reading and accessible navigation for visually impaired developers. + +We could not have reached this important milestone without the help of all our contributors. Since committing to doing development in the open less than four months ago, we’ve consumed over [300 pull requests](https://github.com/Microsoft/vscode/pulls?q=is%3Apr+is%3Aclosed). Whether you created a PR, filed an issue, gave a thumbs up, tweeted, or simply used VS Code in your day-to-day, you’re a part of the team. **Thank you!** + +![installs graphic](installs.png) + +## The History of VS Code + +>*Can we build a code editor fast enough that it doesn’t feel like you’re typing in a browser?* + +It was only a few short years ago that we kicked off what we then called the "Monaco" team. At the time, browsers were just beginning to introduce HTML5, and the race to build faster JavaScript runtimes was in full swing. + +So we set out to answer the question, "Can we build a browser-based code editor that feels native?" Not just an experience for text editing, but source code editing. Suggestion lists, error and warning squiggles, Go to Definition, and more. + +Today, we believe the answer was a resounding "Yes". The editor we built can now be found on some of the most demanding global websites – OneDrive, Bing Code Search, Azure – sites used by millions of people every day. It even ships to 100s of millions of Windows desktops with the F12 tools in Internet Explorer. And that same editor is at the heart of VS Code. + +Of course, to build the editor we needed a development tool. Developers know that one of the best ways to evolve your code quickly is to "dogfood" it: use it the same way your customers will. It therefore made sense that we would create a local Node.js based service to serve up files and the editor in a lightweight development tool. This tool eventually made its way to the cloud as a part of Azure Websites. + +But we strived to go further. We wanted to build a native development tool that developers could install and use anywhere, for any source code. And, from our experience, we believed that it was important to not just have an editor, but one that could help developers accomplish their most common tasks: navigating code, debugging, and working with Git. And, so, Visual Studio Code was born. + +Being built on web technologies made it easy to host the tool in a native cross-platform shell. We decided early on to use, and contribute to, a number of open source technologies – including GitHub’s great Electron shell, which combines web and native UI with a Node.js API. In just a few short months, we were able to release the [first preview](https://blogs.msdn.microsoft.com/somasegar/2015/04/29/introducing-visual-studio-code-visual-studio-2015-rc-application-insights-public-preview-and-net-core-preview-for-linux-and-ma) of Visual Studio Code at //build/ 2015. + +The initial response to a code editor running on OS X, Windows, and Linux was overwhelmingly positive, even with two fundamental gaps in the offering – extensibility and open development. + +Keeping our principle of using VS Code the way our customers do, we decided that the best way to deliver a rich and stable API was to build VS Code using the same API we would expose to extension developers. In fact, the core language services for JavaScript and TypeScript are actually extensions that just happen to be bundled with the distribution. Today, we use VS Code to build and debug VS Code, its extensions, and Node-based services. The same rich TypeScript editing, navigation, and debugging experiences we enjoy when building VS Code are available to everyone developing an extension for VS Code. Six months after our initial preview release, we declared VS Code to be Beta quality at Connect(); 2015, with a full extensibility model, and support in the new Visual Studio Marketplace. + +And at the same time, we open-sourced the VS Code [repository](https://github.com/Microsoft/vscode) and many of our own extensions, and moved to developing Visual Studio Code in the open. + +![timeline graphic](timeline.png) + +## Being "1.0" + +Today, Visual Studio Code delivers on many of the aspects that we imagined during incubation. VS Code has great editing and navigation [experiences](/docs/editor/editingevolved), streamlined [debugging](/docs/editor/debugging), and built-in [Git support](/docs/editor/versioncontrol). + +Developers today love VS Code for its powerful set of built-in features, intuitive editing and debugging experiences, performance and responsiveness, and great language and platform support. The VS Code download is under 40MB including support for 9 additional [languages](/docs/getstarted/locales) (Simplified Chinese, Traditional Chinese, French, German, Italian, Japanese, Korean, Russian and Spanish) and it installs in seconds. With the help of developers like [@zersiax](https://twitter.com/zersiax), VS Code is now [accessible](/docs/editor/accessibility) to visually impaired developers on Windows and soon on OS X and Linux. + +## Community at its Core + +More than anything else, what drives the success of Visual Studio Code is the feedback and interactions from the community. From the beginning, we’ve striven to be as open as possible in our roadmap and vision for VS Code, and in November, we took that a step further by open-sourcing VS Code and adding the ability for anyone to make it better through submitting issues and feedback, making pull requests, or creating extensions. + +The community responded, with huge growth in the number of extensions and the way they’re using VS Code. Today we have extensions for [Node.js](https://marketplace.visualstudio.com/search?term=node&target=VSCode&sortBy=Downloads), [Go](https://marketplace.visualstudio.com/search?term=go&target=VSCode&sortBy=Downloads), [C++](https://marketplace.visualstudio.com/search?term=c++&target=VSCode&sortBy=Downloads), [PHP](https://marketplace.visualstudio.com/search?term=php&target=VSCode&sortBy=Downloads), and [Python](https://marketplace.visualstudio.com/search?term=python&target=VSCode&sortBy=Downloads), as well as many more languages, linters, and tools. And VS Code is being used both by teams of developers, but also in companies like Progressive Insurance, where VS Code is used not just by developers, but analysts and data scientists as well. + +Seeing the support and help the community has already poured into the product, the potential for VS Code has never been greater. + + + +## Looking Ahead + +While we’re excited about releasing 1.0 today, we are even more excited about the future. + +Of course, we will continue to focus on the fundamentals. Performance, stability, accessibility, and compatibility are of utmost importance to our users, and they are to us as well. We will continue to invest in improving developer productivity, guided by the great user feedback on [UserVoice](https://go.microsoft.com/fwlink/?LinkID=533482). We will continue to work with partners and the community to expand support for new languages, and platforms, and experiences. And we will continue to work with you, our community, to build a great tool for you, and for every developer. + +If you haven’t tried out Visual Studio Code yet, please [download](/Download) it and let us know what you think! + +Thanks Again! + +The VS Code Team, [@code](https://twitter.com/code) + diff --git a/blogs/2016/05/04/auto-complete.gif b/blogs/2016/05/04/auto-complete.gif new file mode 100644 index 0000000000000000000000000000000000000000..0826c556943dc409f6c1f0afd23bad883b30057d --- /dev/null +++ b/blogs/2016/05/04/auto-complete.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7900f0a3a64e0567668d243596691eaf3592060240d338a1c074d6fe76aac059 +size 502974 diff --git a/blogs/2016/05/04/complexity-codelens.gif b/blogs/2016/05/04/complexity-codelens.gif new file mode 100644 index 0000000000000000000000000000000000000000..ed60954b81878f7b71049b6921d02b7b6cba11f9 --- /dev/null +++ b/blogs/2016/05/04/complexity-codelens.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b025a398e713acdd35374401f6f5f2089c492d64caf2b721ee6a7ea9c4962f47 +size 473462 diff --git a/blogs/2016/05/04/debugger-for-edge.gif b/blogs/2016/05/04/debugger-for-edge.gif new file mode 100644 index 0000000000000000000000000000000000000000..0052bc12038a7b1d3cf7533322ce7a56c5a58104 --- /dev/null +++ b/blogs/2016/05/04/debugger-for-edge.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0317300c155d0800c85b092af0c556d997b6be3fbe7363c6111db9a6c6d76f45 +size 3778926 diff --git a/blogs/2016/05/04/extension-roundup-may.md b/blogs/2016/05/04/extension-roundup-may.md new file mode 100644 index 0000000000000000000000000000000000000000..3084c0a99c8c02ad354a4458c4be315dcbbe7de1 --- /dev/null +++ b/blogs/2016/05/04/extension-roundup-may.md @@ -0,0 +1,58 @@ +--- +Order: 8 +TOCTitle: Extensions Roundup +PageTitle: Visual Studio Code Extensions Roundup May 2016 +MetaDescription: New, useful, and interesting extensions in Visual Studio Code for May 2016. +Date: 2016-05-04 +ShortDescription: New, useful, and interesting extensions in Visual Studio Code. +Author: Wade Anderson +--- + +# Extensions Roundup + +May 4, 2016 by Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +The Visual Studio Code Extension [Marketplace](https://marketplace.visualstudio.com/VSCode) does a great job of highlighting **Featured**, **Most Popular** and **Newly Added** extensions and we encourage you to browse the site to see what's new and what plug-ins other developers are using. In our extension roundups, we like to call out extensions that we've found interesting and useful. + +If you are new to VS Code extensions, check out the [docs](https://code.visualstudio.com/docs/editor/extension-gallery) for instructions on finding and installing new extensions. + +## Debugger for Edge by Microsoft JS Diagnostics + +>**Install:** From within Visual Studio Code, you can use Quick Open (`kb(workbench.action.quickOpen)`) and paste `ext install debugger-for-edge` then press `kbstyle(Enter)`. + +The same folks who created the very popular [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) extension have published [Debugger for Edge](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-edge) for the Microsoft Edge browser. They were able to reuse the same debugger using the [Chrome Debugger protocol](https://developer.chrome.com/devtools/docs/debugger-protocol). You can learn more about the details in their recent [blog post](https://blogs.windows.com/msedgedev/2016/04/27/introducing-edge-diagnostics-adapter/). + +![debugger for edge](debugger-for-edge.gif) + +## SVG Viewer by cssho + +>**Install:** Quick Open (`kb(workbench.action.quickOpen)`), paste `ext install vscode-svgviewer` and press `kbstyle(Enter)`. + +This highly rated extension lets you view Scalable Vector Graphics (SVG) right from within VS Code. [See more details in the Marketplace](https://marketplace.visualstudio.com/items?itemName=cssho.vscode-svgviewer). + +![SVG viewer](svg-viewer.gif) + +## CodeMetrics by Kiss Tamas + +>**Install:** Quick Open (`kb(workbench.action.quickOpen)`), paste `ext install vscode-codemetrics` and press `kbstyle(Enter)`. + +Curious if your TypeScript source code is getting a little too clever and hard for others to maintain? This [extension](https://marketplace.visualstudio.com/items?itemName=kisstkondoros.vscode-codemetrics) computes the complexity of your code and displays a rating in a CodeLens decoration in the editor. Clicking on the rating brings up the rules used to arrive at the complexity score. + +![complexity CodeLens](complexity-codelens.gif) + +## npm IntelliSense by Christian Kohler + +>**Install:** Quick Open (`kb(workbench.action.quickOpen)`), paste `ext install npm-intellisense` and press `kbstyle(Enter)`. + +Bring quick auto completion into the editor for your workspace's npm modules with this handy [extension](https://marketplace.visualstudio.com/items?itemName=christian-kohler.npm-intellisense). + +![npm IntelliSense](auto-complete.gif) + +## Let us know what extensions you're using + +If you are using an extension that you really like and want to see it featured here, send us a [Tweet](https://twitter.com/code). + +Most extensions are open sourced on [GitHub](https://github.com) so you can learn from the source code and contribute to your favorite extensions. + +Wade Anderson, VS Code Team Member
+[@waderyan_](https://twitter.com/waderyan_) diff --git a/blogs/2016/05/04/svg-viewer.gif b/blogs/2016/05/04/svg-viewer.gif new file mode 100644 index 0000000000000000000000000000000000000000..6183a7f752e9311ef9056090e91c63bed8b60804 --- /dev/null +++ b/blogs/2016/05/04/svg-viewer.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:602459fdedd8893bc3ea603e78ce4033bde066abd9b73c2a86199c1f09ff4131 +size 1027120 diff --git a/blogs/2016/05/09/April2016Release.md b/blogs/2016/05/09/April2016Release.md new file mode 100644 index 0000000000000000000000000000000000000000..e9ead8485b300ea94b48c32f68426be4c8bc0f98 --- /dev/null +++ b/blogs/2016/05/09/April2016Release.md @@ -0,0 +1,43 @@ +--- +Order: +TOCTitle: April 2016 Release +PageTitle: Visual Studio April 2016 Release +MetaDescription: Announcing the Visual Studio Code April 2016 Release +Date: 2016-05-09 +ShortDescription: Announcing the April 2016 Release of VS Code +Author: Chris Dias +--- + +# April 2016 Release + +May 9, 2016 by The VS Code Team, [@code](https://twitter.com/code) + +Today we are releasing the April 2016 build of Visual Studio Code. This is our first monthly release after our 1.0 announcement last month and we really appreciate your support and feedback. + +With this release, we're bringing many improvements to your development experience: + +## Developer Workflow + +* Quickly resize panes by double-clicking editor borders +* Reopen the last closed file using `kb(workbench.action.reopenClosedEditor)` +* Launch your favorite shell when opening a new Terminal from the Explorer or Command Palette + +## Debugging + +* Improved stepping performance when inspecting very large strings or arrays +* Support for deep call stacks +* Node.js improvements such as experimental "smart" code stepping, ES6 type support in Watch, Locals, etc. + +## Extension Authoring + +* Language Server protocol 2.0 is now consistent with core VS Code API +* Automated test support for authoring Debug Adapters +* New APIs for working with folders and JSON files + +Please see our [Release Notes](https://go.microsoft.com/fwlink/?LinkID=533483) for the full list of features and fixes. + +If you have automatic updates turned on (OS X and Windows) then you'll get prompted soon. Otherwise, [download VS Code today](https://code.visualstudio.com)! + +Happy Coding!! + +The VS Code Team diff --git a/blogs/2016/05/23/evolution-of-insiders.md b/blogs/2016/05/23/evolution-of-insiders.md new file mode 100644 index 0000000000000000000000000000000000000000..006ff04ca02c91109bc684969bd6018cfb2db11f --- /dev/null +++ b/blogs/2016/05/23/evolution-of-insiders.md @@ -0,0 +1,55 @@ +--- +Order: +TOCTitle: Evolution of VS Code Insiders +PageTitle: Evolution of Visual Studio Code Insiders +MetaDescription: Evolution of the Visual Studio Code Insiders Build +MetaSocialImage: /assets/blogs/2016/11/30/opengraph_insiders.png +Date: 2016-05-23 +ShortDescription: Evolution of the Insiders Build +Author: Wade Anderson +--- + +# Evolution of the Insiders Build + +May 23, 2016 by Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +Today over five thousand developers use the Visual Studio Code [Insiders Build](https://code.visualstudio.com/blogs/2016/02/01/introducing_insiders_build) for early access to new features and to validate bug fixes. We love the Insiders build because we get valuable feedback and usage insights prior to each Stable release. Thank you for your help! + +Initially, we released an Insiders build once per month, a few days before the Stable release. Over time, we increased the frequency of Insiders builds and today we ship new Insiders builds roughly once a week. + +![value prop of insiders](value_props.svg) + +## Nightly Builds + +Even with weekly Insiders builds, [many users asked](https://github.com/Microsoft/vscode/issues/5453) for access to our nightly builds. + +We initially looked at releasing our internal "Alpha" builds. Alpha builds are what we use to develop VS Code. They are produced from our master branch each night or on demand, if the nightly build has a blocking issue. + +We decided that the overhead of releasing three different builds outweighed the benefits and the difference between weekly and nightly builds was actually low. We then considered retiring the Insiders builds and moving everyone to Alpha but decided that would leave dead ended installations of Insiders builds on everyone's desktops. + +Instead, we've decided to build Insiders nightly from master, move our development team over to the Insiders builds, and retire our internal Alpha builds. We will do development on the same builds we make public. + +For developers using Insiders builds, this means you now have access to fixes and new features a day after check in. If you are already using Insiders builds there is nothing for you to do, you will simply be notified when new builds are available, which will be daily starting in June. + +## Release Frequency + +At a minimum, we will release new Insiders builds daily. However, you may be prompted to update your builds more frequently if we have to fix a blocking issue. Please know we try to minimize these as we're prompted to install along with everyone else. Fortunately, downloads happen in the background, updates are quick, and if you are in the middle of something you can always postpone the upgrade to a more convenient time. + +## Blocking Issues + +We recognize that occasionally, you may encounter blocking issues with the Insiders builds. Rest assured, if it is bad enough, we'll be blocked by it too and a fix will come out quickly. Please submit a new issue and let us know you are using the Insiders build. If the fix will take time, it is always possible to revert to running the Stable build as Insiders builds install and run side-by-side with Stable. + +## Release Notes + +Because we are producing Insiders builds daily, the "Release Notes" become the completed issues for the last day. Handy queries for completed issues can be found in the [Insiders Release Notes wiki page](https://github.com/Microsoft/vscode/wiki/Insiders-Release-Notes). Features being worked on can be found in the [current month's iteration plan](https://github.com/Microsoft/vscode/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Aiteration-plan+). + +## Next Steps + +We will start building and releasing the Insiders builds on a daily basis in conjunction with releasing the [May Stable release](https://github.com/Microsoft/vscode/issues/6105). If you are already using the Insiders build, there is nothing for you to do! Starting in June, you will begin receiving daily update notifications. + +If you are not using the Insiders builds and want to be on the leading edge, using the same builds we use to develop VS Code, head over to our [downloads page](/insiders) and install the Insiders build today. + +See you on [GitHub](https://github.com/Microsoft/vscode), [Twitter](https://go.microsoft.com/fwlink/?LinkID=533687), and [Stack Overflow](https://stackoverflow.com/questions/tagged/vscode)! + +Wade Anderson
+[@waderyan_](https://twitter.com/waderyan_) diff --git a/blogs/2016/05/23/value_props.svg b/blogs/2016/05/23/value_props.svg new file mode 100644 index 0000000000000000000000000000000000000000..36b9c967865a8d53eadb766f4e6c21d53fbb58bd --- /dev/null +++ b/blogs/2016/05/23/value_props.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/blogs/2016/06/27/any-developer-any-language-any-tool.png b/blogs/2016/06/27/any-developer-any-language-any-tool.png new file mode 100644 index 0000000000000000000000000000000000000000..e8f6aee3c53ef780b018aba6bf0d8b36df2217fa Binary files /dev/null and b/blogs/2016/06/27/any-developer-any-language-any-tool.png differ diff --git a/blogs/2016/06/27/common-language-protocol.md b/blogs/2016/06/27/common-language-protocol.md new file mode 100644 index 0000000000000000000000000000000000000000..97136e02624184274ff2bb7218dcd5373d05be88 --- /dev/null +++ b/blogs/2016/06/27/common-language-protocol.md @@ -0,0 +1,59 @@ +--- +Order: 11 +TOCTitle: The Language Server Protocol +PageTitle: Common Language Server Protocol +MetaDescription: A Common Language Server Protocol for any tool and any language. +Date: 2016-06-27 +ShortDescription: Common Language Server Protocol +Author: PJ Meyer +--- + +# A Common Protocol for Languages + +June 27, 2016 by The VS Code Team, [@code](https://twitter.com/code) + +Visual Studio Code is an editor for any developer, no matter what programming language you use. Between languages bundled in the tool or extensions in the [Marketplace](https://marketplace.visualstudio.com/VSCode), we have support for over [150 languages](/blogs/2016/04/14/vscode-1.0.md). We’re also committed to developing VS Code in the open, and making the components that power VS Code available and open source. One of our most notable components is the [Monaco editor](https://github.com/Microsoft/monaco-editor), but another technology that powers VS Code is an [open, JSON-based protocol](https://github.com/Microsoft/language-server-protocol) that anyone can use to add support for a new programming language to VS Code by implementing a "language server". + +![any developer any language any tool](any-developer-any-language-any-tool.png) + +## Any Language, Any Tool + +Today at the [DevNation](https://www.devnation.org) conference in San Francisco, we’ve announced along with [Red Hat and Codenvy](https://developers.redhat.com/blog/2016/06/27/a-common-interface-for-building-developer-tools) that this language server protocol is now being adopted by tool creators and language providers across the industry. For language creators, this means an enhanced tooling experience for their language across a variety of development tools and operating systems, similar to the experience that [TypeScript](https://www.typescriptlang.org) developers or C# developers (via [OmniSharp](http://www.omnisharp.net)) get today. It also means any developer can have a consistent editing experience for their favorite programming language on any tool – even if that tool isn’t VS Code. + +## How it works + +Visual Studio Code provides rich language support for many programming languages. Support for a particular programming language is powered by a **language server** that has a deep understanding of that language. VS Code communicates with these servers to enable rich editing capabilities like 'Errors & Warnings', 'Refactor', and 'Go To Definition'. + +![language server protocol](language-server-protocol.png) + +Here’s an example of how a tool and a language server could communicate semantic information during a routine editing session: + +* The user opens a file (referred to as a *document*) in the tool: The tool notifies the language server that a document is open (`didOpen`) and that the information about that document is maintained by the tool in memory. + +* The user makes edits: The tool notifies the server about the document change (`didChange`) and the semantic information of the program is updated by the language server. As this happens, the language server analyses this information and notifies the tool with the errors and warnings (`diagnostics`) that are found. + +* The user executes 'Go To Definition' on a symbol: The tool sends a `definition` request to the server. The server responds with a `uri` of the document that holds the definition and the `range` inside the document. Based on this information, the tool can open the corresponding document at the defining position. + +* The user closes the document (file): A `didClose` notification is sent from the tool, informing the language server that the document is now no longer in memory and instead maintained by (i.e. stored on) the file system. + +This communication, which takes place over [JSON-RPC](http://www.jsonrpc.org/specification), happens many times over the course of a typical session. + +![language server sequence](language-server-sequence.png) + +This architecture allows for VS Code to interact with multiple language servers, each of which can be implemented in any language (independent of the language the tool was implemented in), and support a variety of features, as long as it utilizes the common JSON-based protocol. + +It also enables a given language server to be implemented once and have different tools take advantage of it. That's why it's exciting that the protocol has been adopted by Codenvy, who have added it to the next generation Eclipse IDE, [Eclipse Che](https://che.eclipse.org/eclipse-che-now-strategic-platform-red-hat), as well as by Red Hat, who are working to publish a standalone language server for Java which can be consumed by any tool that utilizes the protocol. + +## Open Specification + +The complete specification for this protocol is available in a [public GitHub repository](https://github.com/Microsoft/language-server-protocol), as is a [history of how the protocol has evolved](https://github.com/Microsoft/language-server-protocol/wiki/Protocol-History) to date. As it continues to be adopted by more languages and tools, we intend to support and evolve the protocol, along with partners like Red Hat, Codenvy, and others in the open source community. Anyone can ask questions, file issues, or submit pull requests on the repo, just like any other open source project. + +## What's Next + +This is just the start – communities for programming languages like OmniSharp (C#), JSON, C++, xText, JavaFX, and R have made commitments to release language servers for their languages in the future. A full [list of protocol implementations](https://github.com/Microsoft/language-server-protocol/wiki/Protocol-Implementations), including language servers, editors, and SDKs is available on the GitHub repo. + +If you want to learn more, [view the breakout session](https://www.youtube.com/watch?v=2GqpdfIAhz8), check out the blog posts from [Red Hat](https://developers.redhat.com/blog/2016/06/27/a-common-interface-for-building-developer-tools) and the [Eclipse Che](https://che.eclipse.org/eclipse-che-now-strategic-platform-red-hat) team, and visit the [language server protocol repo](https://github.com/microsoft/language-server-protocol) on GitHub. There is even a [Language Server Walkthrough](/docs/extensions/example-language-server.md) where you can step through the source code of a working language server implemented in TypeScript and Node.js. But of course you can implement a language server in any language! + +Happy Coding! + +The VS Code Team, [@code](https://twitter.com/code) diff --git a/blogs/2016/06/27/language-server-protocol.png b/blogs/2016/06/27/language-server-protocol.png new file mode 100644 index 0000000000000000000000000000000000000000..4daf05625a598e589d4e8c744462a97c25a660c6 Binary files /dev/null and b/blogs/2016/06/27/language-server-protocol.png differ diff --git a/blogs/2016/06/27/language-server-sequence.png b/blogs/2016/06/27/language-server-sequence.png new file mode 100644 index 0000000000000000000000000000000000000000..7f9415093c66c6f6dd28c2635fe7bb0d8ef0a1c8 Binary files /dev/null and b/blogs/2016/06/27/language-server-sequence.png differ diff --git a/blogs/2016/07/29/annotate-animation.gif b/blogs/2016/07/29/annotate-animation.gif new file mode 100644 index 0000000000000000000000000000000000000000..db0f618b38e2f3c6882b83debc23823fb046f7d2 --- /dev/null +++ b/blogs/2016/07/29/annotate-animation.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1136c6d27dc90bd8a41801fab45be037d020b08a690252e288fc2213ef0c142e +size 1019972 diff --git a/blogs/2016/07/29/extensions-roundup-git.md b/blogs/2016/07/29/extensions-roundup-git.md new file mode 100644 index 0000000000000000000000000000000000000000..4d1c391e0068c9279af412605613356a64e837fc --- /dev/null +++ b/blogs/2016/07/29/extensions-roundup-git.md @@ -0,0 +1,107 @@ +--- +Order: 12 +TOCTitle: Extensions Roundup - Fun with Git +PageTitle: Visual Studio Code Extensions Roundup - Git August 2016 +MetaDescription: Extensions to super power your Git workflow. +Date: 2016-08-02 +ShortDescription: Extensions to super power your Git workflow. +Author: Wade Anderson +--- +# Extensions Roundup - Fun with Git + +August 2, 2016 by Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +The first extension I built for Visual Studio Code was called [Git Blame](https://marketplace.visualstudio.com/items?itemName=waderyan.gitblame). It lets you quickly see which developer most recently modified the currently selected line ("blame"). It was simple and effective. Since the time when I built this extension, there have been many more awesome Git extensions added to the VS Code [Marketplace](https://marketplace.visualstudio.com/VSCode). Here are some of my favorite. + +> Tip: Install any of these extensions by clicking the Extensions View button, typing the name of the extension in the Search box, and clicking **Install**. See more instructions [here](https://code.visualstudio.com/docs/editor/extension-gallery.md#browse-and-install-extensions). + +## Annotator + +Marketplace - [Annotator](https://marketplace.visualstudio.com/items?itemName=ryu1kn.annotator) + +Publisher - [Ryuichi Inagaki](https://marketplace.visualstudio.com/search?term=publisher%3A%22Ryuichi%20Inagaki%22&target=VSCode) + +This extension takes "blame" information to the next level. You can see all the commit information in the gutter and it's clickable! When you click on the blame, you see the diff of that commit. The gutter color is darker for older commits and lighter for the most recent commits, which was a smooth way to create the UI. Truly an excellent extension and my personal favorite. + +![animation annotator](annotate-animation.gif) + +## Git History + +Marketplace - [Git History](https://marketplace.visualstudio.com/items?itemName=donjayamanne.githistory) + +Publisher - [Don Jayamanne](https://marketplace.visualstudio.com/search?term=publisher%3A%22Don%20Jayamanne%22&target=VSCode) + +With this extension, you will find a very rich feature set for your Git workflow: + +- View history of a file or line. +- Compare a previous copy of a file against the local workspace version. +- View the changes to the active line. + +![animation of Git history](git-history-animation.gif) + +## Share Code + +Marketplace - [Share Code](https://marketplace.visualstudio.com/items?itemName=RolandGreim.sharecode) + +Publisher - [Roland Greim](https://marketplace.visualstudio.com/search?term=publisher%3A%22Roland%20Greim%22&target=VSCode) + +Ever wanted to send your code to Pastebin or a GitHub Gist? Open the file you want to share and share it with a couple commands in the **Command Palette**. + +![animation of share code](share-code-animation.gif) + +## Open in GitHub + +Marketplace - [Open in GitHub](https://marketplace.visualstudio.com/items?itemName=ziyasal.vscode-open-in-github) + +Publisher - [ziyasal](https://marketplace.visualstudio.com/search?term=publisher%3A%22ziyasal%22&target=VSCode) + +One of the most popular extensions used by the VS Code team. This extension allows you to open the current line in GitHub. + +![open in GitHub extension](open-in-github.png) + +## Git Project Manager + +Marketplace - [Git Project Manager](https://marketplace.visualstudio.com/items?itemName=felipecaputo.git-project-manager) + +Publisher - [Felipe Caputo](https://marketplace.visualstudio.com/search?term=publisher%3A%22Felipe%20Caputo%22&target=VSCode) + +Do you have multiple Git projects that you want to open with VS Code? Install this extension and quickly switch between your projects. + +![Git project manager extension](git-project-manager.png) + +## Partial Diff + +Marketplace - [Partial Diff](https://marketplace.visualstudio.com/items?itemName=ryu1kn.partial-diff) + +Publisher - [Ryuichi Inagaki](https://marketplace.visualstudio.com/search?term=publisher%3A%22Ryuichi%20Inagaki%22&target=VSCode) + +Ryuichi's second time on this list (he is busy)! This extension isn't Git specific but lets you diff selected text which I have found very useful while coding my projects. + +![partial diff extension animation](partial-diff.gif) + +## gitignore + +Marketplace - [gitignore](https://marketplace.visualstudio.com/items?itemName=michelemelluso.gitignore) + +Publisher - [michelemelluso](https://marketplace.visualstudio.com/search?term=publisher%3A%22michelemelluso%22&target=VSCode) + +This is the first of two gitignore extensions. With this gitignore extension, simply right click and add a file to your `.gitignore` configuration! + +![gitignore right click extension](gitignore-rightclick.png) + +## gitignore #2 + +Marketplace - [gitignore](https://marketplace.visualstudio.com/items?itemName=codezombiech.gitignore) + +Publisher - [CodeZombie](https://marketplace.visualstudio.com/search?term=publisher%3A%22CodeZombie%22&target=VSCode) + +The second gitignore extension (note that they are from different publishers) will pull in template `.gitignore` files. Are you coding in Python and want all the "usual" Python `.gitignore` configurations? Install this extension and run a simple command to pull down the `.gitignore` from [github/gitignore](https://github.com/github/gitignore). + +![gitignore template extension](gitignore-template.png) + +## Want to see your extension featured? + +Have other extensions you like or want to see your extension in the next roundup? Ping me on [Twitter](https://twitter.com/waderyan_)! + +Wade Anderson, VS Code Team Member
+[@waderyan_](https://twitter.com/waderyan_) diff --git a/blogs/2016/07/29/git-history-animation.gif b/blogs/2016/07/29/git-history-animation.gif new file mode 100644 index 0000000000000000000000000000000000000000..bb3e53f30db7606e24a54051b80f13aecccf1981 --- /dev/null +++ b/blogs/2016/07/29/git-history-animation.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6656f25c88891e388cba800bb58d1db7b65f5bd56ea5f0741f18a725f367ab51 +size 2477299 diff --git a/blogs/2016/07/29/git-project-manager.png b/blogs/2016/07/29/git-project-manager.png new file mode 100644 index 0000000000000000000000000000000000000000..c20a20ed8395015563ebca3e870215e7373e401e Binary files /dev/null and b/blogs/2016/07/29/git-project-manager.png differ diff --git a/blogs/2016/07/29/gitignore-rightclick.png b/blogs/2016/07/29/gitignore-rightclick.png new file mode 100644 index 0000000000000000000000000000000000000000..a5a4643430798112f6ee950bfd8f47f729c10c1c Binary files /dev/null and b/blogs/2016/07/29/gitignore-rightclick.png differ diff --git a/blogs/2016/07/29/gitignore-template.png b/blogs/2016/07/29/gitignore-template.png new file mode 100644 index 0000000000000000000000000000000000000000..31b87d4d578f4f4b6ce4c7b686282a5b947a0795 Binary files /dev/null and b/blogs/2016/07/29/gitignore-template.png differ diff --git a/blogs/2016/07/29/open-in-github.png b/blogs/2016/07/29/open-in-github.png new file mode 100644 index 0000000000000000000000000000000000000000..b94d1759afbfc37f2dfd29f8857d15e6aeaa11a4 Binary files /dev/null and b/blogs/2016/07/29/open-in-github.png differ diff --git a/blogs/2016/07/29/partial-diff.gif b/blogs/2016/07/29/partial-diff.gif new file mode 100644 index 0000000000000000000000000000000000000000..ee31a8d26ed0e44b6ce259a466a5ffcf939cbbcf --- /dev/null +++ b/blogs/2016/07/29/partial-diff.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b454fba7c912d0255d628edf70cf39887f19e33df2181be2d14b45b3f9cbc37b +size 754862 diff --git a/blogs/2016/07/29/share-code-animation.gif b/blogs/2016/07/29/share-code-animation.gif new file mode 100644 index 0000000000000000000000000000000000000000..535ab290689e8d62fc5e3ec86fc025d4a26c6593 --- /dev/null +++ b/blogs/2016/07/29/share-code-animation.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e2633106f8b9271002911b83bb4e48c508b1a1aaf963ae5fc4cecc0901cebb61 +size 226793 diff --git a/blogs/2016/08/15/introvideos.md b/blogs/2016/08/15/introvideos.md new file mode 100644 index 0000000000000000000000000000000000000000..4de8851b48909b67b1806b5117eda9aa4d2b7ea2 --- /dev/null +++ b/blogs/2016/08/15/introvideos.md @@ -0,0 +1,34 @@ +--- +Order: +TOCTitle: Intro Videos +PageTitle: Visual Studio Code Introductory Videos +MetaDescription: We want to help people get going with VS Code. Watch our new introductory videos to jump start your work with VS Code. +Date: 2016-08-15 +ShortDescription: Watch our new intro videos to jump start your work with VS Code. +Author: Wade Anderson +--- + +# Announcing Intro Videos + +August 15, 2016 by Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +On the product team, we're constantly trying to make Visual Studio Code better. We spend hours in interviews, usability studies, and interacting with you online. + +One theme we hear from users new to VS Code is that they would like more on-boarding material. They want to be able to get up and running with VS Code quickly and be able to take advantage of its powerful features right away. + +To help new users, today we are announcing a set of introductory videos. These videos give basic introductions to downloading and installing VS Code and using features like IntelliSense, debugging, version control and more. + +## Take a Look + +Navigate to [Intro Videos - Overview](/docs/getstarted/introvideos.md) to get started. + +Below is the first video covering downloading, installing, and the basics of using VS Code: + + + +You can see the video outline [here](/docs/introvideos/basics.md) as well as additional introductory learning resources. + +We want your feedback. What other videos would you like to see? Leave feedback in [this survey](https://www.surveymonkey.com/r/H9W7K8J) or ping me on [Twitter](https://twitter.com/waderyan_). + +Wade Anderson, VS Code Team Member
+[@waderyan_](https://twitter.com/waderyan_) diff --git a/blogs/2016/08/19/github_reaction.gif b/blogs/2016/08/19/github_reaction.gif new file mode 100644 index 0000000000000000000000000000000000000000..143668de0ee5af6c885d7635e8ea1d537f6cca55 --- /dev/null +++ b/blogs/2016/08/19/github_reaction.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:626a0d3e3322fe081a7020385c66d2bf9f5df59cfae9cbe53cb5b1dc1413b61d +size 259921 diff --git a/blogs/2016/08/19/goodbyeuservoice.md b/blogs/2016/08/19/goodbyeuservoice.md new file mode 100644 index 0000000000000000000000000000000000000000..352520b1789bb43e58e63eb5e87d4003eb88b692 --- /dev/null +++ b/blogs/2016/08/19/goodbyeuservoice.md @@ -0,0 +1,38 @@ +--- +Order: +TOCTitle: Goodbye User Voice +PageTitle: Goodbye User Voice +MetaDescription: Visual Studio Code is closing User Voice in favor of GitHub reactions. +Date: 2016-08-23 +ShortDescription: Visual Studio Code is closing User Voice in favor of GitHub reactions. +Author: Wade Anderson +--- + +# Goodbye User Voice, Hello GitHub Reactions! + +August 23, 2016 by Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +## Feedback Channels + +Visual Studio Code's [User Voice site](https://visualstudio.uservoice.com/forums/293070-visual-studio-code) has always been the place for the community to suggest and vote on feature requests for VS Code. The ability to see the requests with the top votes or the most activity has allowed us to prioritize the VS Code backlog and deliver many of the top requests over the past 18 months. For example, we’ve added [Extensions](https://visualstudio.uservoice.com/forums/293070-visual-studio-code/suggestions/9181439-plugins) (plugins), [Tabs](https://visualstudio.uservoice.com/forums/293070-visual-studio-code/suggestions/7752519-implement-tabs) (tabbed headings) and an [Integrated Terminal](https://visualstudio.uservoice.com/forums/293070-visual-studio-code/suggestions/7752357-integrated-terminal), all because of your feedback and participation in User Voice. + +The challenge with User Voice is that it is a separate feedback channel for the team to monitor and maintain. Today we spend the majority of our time in [GitHub](https://github.com/Microsoft/vscode), but we also monitor [Twitter](https://twitter.com/code), [Stack Overflow](https://stackoverflow.com/questions/tagged/vscode), and [Gitter](https://gitter.im/Microsoft/vscode) along with [User Voice](https://visualstudio.uservoice.com/forums/293070-visual-studio-code). The management of User Voice requests is labor intensive and we haven't been as responsive to the community as we'd like. + +## GitHub Reactions + +Recently, GitHub introduced the ability to [add reactions to issues](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments). This feature replaces the key value proposition of User Voice, which has been the ability to vote on a request. It is now possible for the community to not only comment on an issue in GitHub, but also provide a thumbs up/thumbs down vote. This means we can use the same tools and workflows to sort and manage feature requests as we do to manage bugs. + +![github reactions animation](github_reaction.gif) + +## Retiring User Voice + +As a result, we are "retiring" the [VS Code User Voice site](https://visualstudio.uservoice.com/forums/293070-visual-studio-code) and asking the community to submit and vote on issues in GitHub. To ease the transition, we’ve decided to migrate the current [top 50 User Voice requests](https://github.com/Microsoft/vscode/issues/10715), as of 08/18/2016, to GitHub. We will triage these requests and migrate them to the appropriate repositories. If a feature request is more closely aligned with an extension and not the core VS Code product, we’ll move the request to an existing extension's repository or label it as an ["*extension-candidate"](https://github.com/Microsoft/vscode/labels/*extension-candidate). + +If your request is not on this list or if you have a new request, please open a new GitHub issue following these [guidelines](https://github.com/Microsoft/vscode/blob/master/CONTRIBUTING.md). After you create an issue, we will run it through our [issue tracking](https://github.com/Microsoft/vscode/wiki/Issue-Tracking) workflow. The inbox tracker for the week assigns your issue to the team member who owns the relevant area of code. The owner will then assign the correct labels and ask for more information if necessary. During milestone planning, we review the open issues and assign the ones we plan to work on to a milestone. + +Thank you again for your continuing feedback and hopefully this change will let us be more responsive and ultimately deliver more of the experiences you want and need in VS Code. + +Happy Coding. + +Wade Anderson, VS Code Team Member
+[@waderyan_](https://twitter.com/waderyan_) diff --git a/blogs/2016/08/22/introducing-ios-web-debugging-for-vs-code-on-windows-and-mac.md b/blogs/2016/08/22/introducing-ios-web-debugging-for-vs-code-on-windows-and-mac.md new file mode 100644 index 0000000000000000000000000000000000000000..f896c14a8355d25e1179ca5f51dd31c028c917ae --- /dev/null +++ b/blogs/2016/08/22/introducing-ios-web-debugging-for-vs-code-on-windows-and-mac.md @@ -0,0 +1,59 @@ +--- +Order: +TOCTitle: iOS Web Debugging +PageTitle: Introducing iOS Web Debugging for VS Code on Windows and Mac +MetaDescription: iOS Web Debugging for VS Code on Windows and Mac +Date: 2016-08-24 +ShortDescription: Today debugging websites running on iOS devices are limited to a subset of developers, as the Safari Web Inspector (Safari DevTools) requires an instance of desktop Safari which only is available for macOS users. With our new debugger we are aiming to change that, as our iOS Web Debugger for Visual Studio Code works both on Mac and Windows. +Author: Kenneth Auchenberg +--- +# iOS Web Debugging on Windows and Mac + +August 24, 2016 by [Kenneth Auchenberg](https://twitter.com/auchenberg) + +## Update + +The [iOS Web debugger](https://github.com/Microsoft/vscode-ios-web-debug) has been deprecated and we now recommend that you use the [RemoteDebug iOS WebKit Adapter](https://github.com/RemoteDebug/remotedebug-ios-webkit-adapter) together with Visual Studio Code. To learn more, see this introductory [guide](https://medium.com/@auchenberg/hello-remotedebug-ios-webkit-adapter-debug-safari-and-ios-webviews-from-anywhere-2a8553df7465) to the RemoteDebug iOS WebKit Adapter. + +## Introduction + +Debugging websites running on iOS devices is accessible only to a subset of developers. For example, using the Safari Web Inspector (Safari DevTools) requires an instance of desktop Safari which only is available for macOS users. Today, we’re enabling mobile web developers to debug JavaScript running on their iOS devices directly from their editor with a new [iOS Web Debugger for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-ios-web). This debug extension works on both **Mac and Windows**. + +![Demo](ios-debugger-splash.png) + +Our new iOS Web Debugger works quite similar to our Chrome debugger which we [introduced back in February](https://code.visualstudio.com/blogs/2016/02/23/introducing-chrome-debugger-for-vs-code). Under the hood, it’s the same debugger running inside VS Code, which is powered by our open source [vscode-chrome-debug-core](https://github.com/Microsoft/vscode-chrome-debug-core) library. To make the connection from our debugging library to the iOS device, we are leveraging two open source projects, [ios-webkit-debug-proxy](https://github.com/google/ios-webkit-debug-proxy) and [ios-webkit-debug-proxy-win32](https://github.com/artygus/ios-webkit-debug-proxy-win32), that enables communication with the iOS devices over USB through the WebKit Remote Debugging Protocol. The protocol is compatible with the Chrome Debugging Protocol for the script debugging APIs, and this means our debugger works without additional mapping logic. + +## Enabling easy local development through emulated port forwarding + +When developing websites running locally, it’s a cumbersome process to enable mobile devices access your local development server, which usually is a HTTP server running on localhost. To make this easier, platforms like Android supports port-forwarding natively, but iOS doesn’t support this. + +So we found a way to emulate port forwarding by adding the option to start an instance of [localtunnel](https://localtunnel.github.io/www/), that behind the scenes creates HTTP tunnel from your local computer to the public internet for the specified `tunnelPort` property. This HTTP tunnel is then used by the iOS device to get access to your local development server, just as any other public website. + +![Demo](ios-debugger-demo.gif) + +## Getting started + +To get started, open the **Extensions** view (`kb(workbench.view.extensions)`). When the extension list appears, type "ios" to filter the list and install the Debugger for iOS Web extension. You'll then create a launch-configuration file which we explain in detail in our README [right here](https://github.com/Microsoft/vscode-ios-web-debug). + +## Supported features + +In this release, we support the following features: + +- Setting breakpoints, including in source files when source maps are enabled +- Stepping +- Stack traces +- The Locals pane +- Debugging eval scripts, script tags, and scripts that are added dynamically +- Watches +- Console +- Virtual port forwarding via HTTP tunnel from local computer. + +## Experimenting out in the open + +Our new iOS Web Debugger is a **public experiment** and this means we are releasing it to the public to find out if **integrated script debugging for iOS** are valuable for developers, so please let us know what you think. + +If you have any issues or ideas for improvements, feel free to reach out to us on [Twitter](https://twitter.com/code) or on [GitHub](https://github.com/Microsoft/vscode-ios-web-debug). + +– + +[Kenneth Auchenberg](https://twitter.com/auchenberg), Program Manager, JavaScript Diagnostics diff --git a/blogs/2016/08/22/ios-debugger-demo.gif b/blogs/2016/08/22/ios-debugger-demo.gif new file mode 100644 index 0000000000000000000000000000000000000000..435fd49b85bcf0d8a9cff1c39b43a96cb26c9fa9 --- /dev/null +++ b/blogs/2016/08/22/ios-debugger-demo.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6fe7cc94ce6ce5677af7e05d84111735ac9dac057d88fbb1d121000f0a8099f4 +size 2925514 diff --git a/blogs/2016/08/22/ios-debugger-splash.png b/blogs/2016/08/22/ios-debugger-splash.png new file mode 100644 index 0000000000000000000000000000000000000000..7d584d163b3ce6c74db9bec46fb9bdb053df9d99 Binary files /dev/null and b/blogs/2016/08/22/ios-debugger-splash.png differ diff --git a/blogs/2016/09/08/i-heart-seti.png b/blogs/2016/09/08/i-heart-seti.png new file mode 100644 index 0000000000000000000000000000000000000000..6c1db499a572a0dad5e034342429b6243b9762e7 Binary files /dev/null and b/blogs/2016/09/08/i-heart-seti.png differ diff --git a/blogs/2016/09/08/icon-themes.md b/blogs/2016/09/08/icon-themes.md new file mode 100644 index 0000000000000000000000000000000000000000..894745649f827bfa65cd6e11bf3458102ffe7d01 --- /dev/null +++ b/blogs/2016/09/08/icon-themes.md @@ -0,0 +1,71 @@ +--- +Order: 16 +TOCTitle: File Icon Themes +PageTitle: File and Folder Icons in Visual Studio Code +MetaDescription: File and Folder Icons in Visual Studio Code +Date: 2016-09-08 +ShortDescription: The Visual Studio Code Explorer now supports file and folder icons. VS Code ships with two icon themes and more are available on the Marketplace. +Author: Chris Dias +--- + +# File and Folder Icons in VS Code! + +September 8, 2016 by Chris Dias, [@chrisdias](https://twitter.com/chrisdias) + +## Rebellion. Mutiny. Revolt. Uprising. + +These words all describe the first time we added icons to the File Explorer tree in VS Code, back in 2014. [@dmitar-asenov](https://github.com/dimitar-asenov) was an intern in [@egamma](https://github.com/egamma)'s Zurich lab and spent a couple of hours hacking in a basic set of icons because he wanted to differentiate between files and folders when quickly glancing at the tree. + +When we started work on the "Monaco" editor, icons in the Explorer didn't make the cut for a lightweight editor. The team loved the simple, clean look of an icon-less tree. To us, icons felt heavy and provided little value. We worried about maintaining 100+ icons and keeping them in sync with the Visual Studio IDE. We left in the icon implementation in case we changed our minds in the future, but we never turned it on. + +Fast forward to February 2016. [PR 3200](https://github.com/Microsoft/vscode/pull/3200) forced us to have the discussion again, but given our "1.0" deliverables and other feature requests (such as Tabs), we had to push out the conversation. + +As we planned the August 2016 release, many of the [top feature requests](https://github.com/Microsoft/vscode/issues?q=is%3Aopen+is%3Aissue+label%3Afeature-request) had been addressed and support for icons bubbled to the top: + +* Over [200 thumbs up on GitHub](https://github.com/Microsoft/vscode/issues/211). +* Number 9 with almost 2500 votes on the [recently retired](https://code.visualstudio.com/blogs/2016/08/19/goodbyeuservoice) User Voice list. +* With over 200K downloads, 170 reviews, and a 5 star rating, [Roberto Huertas](https://github.com/robertohuertasm)' [vscode-icons](https://marketplace.visualstudio.com/items?itemName=robertohuertasm.vscode-icons) extension had become the 5th most popular extension in the Marketplace. + +![vscode-icons extension](vscode-icons.png) + +Maybe we were wrong back in 2014. The 10 people on the VS Code team at that time hardly constituted a statistically significant data set. 200 thumbs up said we needed to listen to this feedback and look at this again. Thank you for the feedback! + +It was clear from the start that we needed to make icon theming an extension point to VS Code. It would be impossible to come up with a single set of icons that everyone agreed upon. Without a proper extension mechanism, Roberto was forced to patch the installed sources in order to make the vscode-icons extension work properly. + +Not only did this approach mean that the extension needed to be reinstalled on every daily or monthly update of VS Code, it opened up to a new class of issues which we could not easily diagnose or fix, since the core product was being modified after we shipped it. In the future, we'll be working on minimizing the risk of corrupting the core product so that users are not forced to reinstall VS Code as the result of installing an extension. + +## File Icon Themes + +With the 1.5 release of VS Code, we now support icons to the File Explorer. + +From the **File** > **Preferences** menu or the **Command Palette** (`kb(workbench.action.showCommands)`) search for File Icon Theme: + +![select icon theme](select-icon-theme.png) + +Initially we were going to ship with a single, simple theme called **Minimal**, which has folder open/closed icons as well as a single file icon for all types. + +![minimal icon theme](minimal-icon-theme.png) + +## Seti Icon Theme + +As we tested different icons and worked with Roberto to ensure we could support his key scenarios, we discovered the [Seti UI](https://github.com/jesseweed/seti-ui) icons, first popularized in Sublime Text. + +And we were converted. + +![I heart seti](i-heart-seti.png) + +Most of the team now runs on the Seti icons so we decided to include them in the product for everyone to enjoy. Simply choose the **Seti (Visual Studio Code)** icon theme in the File Icon Theme selection dialog. + +![Seti icon theme](seti-icon-theme.png) + +>**Note:** You can arrow up and down through the File Icon Theme list and see a preview of the selected theme, just as you can with the Color Themes! + +## Create your own Icon Theme + +It is incredibly easy for extension authors to create your own File Icon Theme packs, check out the raw documentation [here](https://github.com/Microsoft/vscode/issues/10804) and the ["Adding a new Icon Theme"](/docs/extensions/themes-snippets-colorizers.md#adding-a-new-icon-theme) topic in the VS Code docs. Looking ahead, we will continue to fill out the API based on your feedback. + +Thanks again for all of your feedback and thanks to Roberto for building a popular extension and helping us deliver great APIs. + +Happy Coding, + +Chris Dias \ No newline at end of file diff --git a/blogs/2016/09/08/minimal-icon-theme.png b/blogs/2016/09/08/minimal-icon-theme.png new file mode 100644 index 0000000000000000000000000000000000000000..bdc2ce6fe8de7d9754a1f9b6b4fb1d5adf2e2415 Binary files /dev/null and b/blogs/2016/09/08/minimal-icon-theme.png differ diff --git a/blogs/2016/09/08/select-icon-theme.png b/blogs/2016/09/08/select-icon-theme.png new file mode 100644 index 0000000000000000000000000000000000000000..7f48a848098c40bc1abb6124cfd8d716c363293e Binary files /dev/null and b/blogs/2016/09/08/select-icon-theme.png differ diff --git a/blogs/2016/09/08/seti-icon-theme.png b/blogs/2016/09/08/seti-icon-theme.png new file mode 100644 index 0000000000000000000000000000000000000000..a5bea6e6fbd9d8d29649af75d1f2e9bc0138e39f Binary files /dev/null and b/blogs/2016/09/08/seti-icon-theme.png differ diff --git a/blogs/2016/09/08/vscode-icons.png b/blogs/2016/09/08/vscode-icons.png new file mode 100644 index 0000000000000000000000000000000000000000..0d3cf463324b08d4967e571d6c5a3b627a843228 Binary files /dev/null and b/blogs/2016/09/08/vscode-icons.png differ diff --git a/blogs/2016/09/14/eslint.gif b/blogs/2016/09/14/eslint.gif new file mode 100644 index 0000000000000000000000000000000000000000..fcb948229164ff07c04117cd7f110489633cab6c Binary files /dev/null and b/blogs/2016/09/14/eslint.gif differ diff --git a/blogs/2016/09/14/javascript_snippets.png b/blogs/2016/09/14/javascript_snippets.png new file mode 100644 index 0000000000000000000000000000000000000000..ab971155801181b055ba1776ba608b7bfc64baca Binary files /dev/null and b/blogs/2016/09/14/javascript_snippets.png differ diff --git a/blogs/2016/09/14/js_roundup_1.md b/blogs/2016/09/14/js_roundup_1.md new file mode 100644 index 0000000000000000000000000000000000000000..a5c9f63123c09e3726286ce50b83ab6a84fbd713 --- /dev/null +++ b/blogs/2016/09/14/js_roundup_1.md @@ -0,0 +1,74 @@ +--- +Order: 17 +TOCTitle: JavaScript Extensions Part 1 +PageTitle: Visual Studio Code JavaScript Extensions Part 1 Sep 2016 +MetaDescription: Essential JavaScript extensions for Visual Studio Code. +Date: 2016-09-14 +ShortDescription: Essential JavaScript extensions for Visual Studio Code. +Author: Wade Anderson +--- + +# JavaScript Extensions Part 1 + +September 14, 2016 by Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +> This is part one in a series on JavaScript extensions. + +I learned JavaScript during an internship in the summer of 2013. Although not a difficult programming language, JavaScript didn't come easy. I used a lightweight editor along with the rest of my team and missed the deep language integration features of Visual Studio (C#) and Eclipse (Java). + +Visual Studio Code is not an IDE, but you can extend it to do many of the things an IDE can do. VS Code extensions effectively bridge the gap between an IDE and a lightweight editor (read [here](/docs/extensionAPI/patterns-and-principles.md#core-concepts) to learn how we maintain high performance when extensions are added). + +Below are some of the essential JavaScript extensions that I and many of you are using every day. + +> **Tip:** Install any of these extensions by clicking the Extensions View button, typing the name of the extension in the Search box, and clicking **Install**. See more instructions [here](/docs/editor/extension-gallery.md#browse-and-install-extensions). + +## ESLint + +Marketplace - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) + +Publisher - [Dirk Baeumer](https://marketplace.visualstudio.com/search?term=publisher%3A%22Dirk%20Baeumer%22&target=VSCode) + +Easily integrate [ESLint](http://eslint.org/) into your project. Dirk is a member of the VS Code team and he maintains this extension and just released an update. If ESLint isn't your favorite linter, choose among a variety of other linter extensions, including [JSHint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.jshint), [JSCS](https://marketplace.visualstudio.com/items?itemName=ms-vscode.jscs), and [JS Standard](https://marketplace.visualstudio.com/items?itemName=shinnn.standard). + +Read more about setting up JavaScript linters in the VS Code [documentation](/docs/languages/javascript.md#linters). + +![eslint animation](eslint.gif) + +## JavaScript (ES6) code snippets + +Marketplace - [JavaScript (ES6) code snippets](https://marketplace.visualstudio.com/items?itemName=xabikos.JavaScriptSnippets) + +Publisher - [charalampos karypidis](https://marketplace.visualstudio.com/search?term=publisher%3A%22charalampos%20karypidis%22&target=VSCode) + +VS Code comes with many built-in code snippets. The **JavaScript (ES6) code snippets** extension adds snippets for ES6 (ECMAScript 6) syntax. Here is a small sampling of the snippets provided by this extension. See the extension's [README](https://marketplace.visualstudio.com/items?itemName=xabikos.JavaScriptSnippets) to see the dozens of snippets this pack gives you. + +![javascript snippets](javascript_snippets.png) + +You can read more about JavaScript snippets in the VS Code [documentation](/docs/languages/javascript.md#snippets). For additional snippet packs, including [Angular 1](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular1), [Angular 2](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular2), [Bootstrap 3](https://marketplace.visualstudio.com/items?itemName=wcwhitehead.bootstrap-3-snippets), [ReactJs](https://marketplace.visualstudio.com/items?itemName=xabikos.ReactSnippets), and [jQuery](https://marketplace.visualstudio.com/items?itemName=donjayamanne.jquerysnippets), check out the Marketplace's [Snippets category](https://marketplace.visualstudio.com/vscode/Snippets?sortBy=Downloads). + +## Path IntelliSense + +Marketplace - [Path IntelliSense](https://marketplace.visualstudio.com/items?itemName=christian-kohler.path-intellisense) + +Publisher - [Christian Kohler](https://marketplace.visualstudio.com/search?term=publisher%3A%22Christian%20Kohler%22&target=VSCode) + +This extension autocompletes file paths in your source code. Use this in JavaScript, HTML, CSS files and more. + +![path intellisense](path_intellisense.gif) + +## npm IntelliSense + +Marketplace - [npm IntelliSense](https://marketplace.visualstudio.com/items?itemName=christian-kohler.npm-intellisense) + +Publisher - [Christian Kohler](https://marketplace.visualstudio.com/search?term=publisher%3A%22Christian%20Kohler%22&target=VSCode) + +A second incredibly useful extension from Christian Kohler. This extension provides IntelliSense for npm modules. + +![npm intellisense](npm_intellisense.gif) + +## Want to see your extension featured? + +Have other extensions you like or want to see your extension in the next roundup? Ping me on [Twitter](https://twitter.com/waderyan_)! + +Wade Anderson, VS Code Team Member
+[@waderyan_](https://twitter.com/waderyan_) diff --git a/blogs/2016/09/14/npm_intellisense.gif b/blogs/2016/09/14/npm_intellisense.gif new file mode 100644 index 0000000000000000000000000000000000000000..0826c556943dc409f6c1f0afd23bad883b30057d --- /dev/null +++ b/blogs/2016/09/14/npm_intellisense.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7900f0a3a64e0567668d243596691eaf3592060240d338a1c074d6fe76aac059 +size 502974 diff --git a/blogs/2016/09/14/path_intellisense.gif b/blogs/2016/09/14/path_intellisense.gif new file mode 100644 index 0000000000000000000000000000000000000000..b2560d7f9b2ecf53a3574f026d40c91fba2b6044 Binary files /dev/null and b/blogs/2016/09/14/path_intellisense.gif differ diff --git a/blogs/2016/10/31/chrome_debugger.png b/blogs/2016/10/31/chrome_debugger.png new file mode 100644 index 0000000000000000000000000000000000000000..c3d4a5068a71e8f24595ab7109596afd3643dc2e --- /dev/null +++ b/blogs/2016/10/31/chrome_debugger.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7000291fe613d6f077bd8547517af605aefc8a38179591c3b24a76722afca853 +size 848158 diff --git a/blogs/2016/10/31/document_this.gif b/blogs/2016/10/31/document_this.gif new file mode 100644 index 0000000000000000000000000000000000000000..a1aa4ed439b8c3f22cfb6f66dca8d89d1444a8db --- /dev/null +++ b/blogs/2016/10/31/document_this.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:768de8e496bb661a4d0ac7ff65041c129a9140b30651ddf3c00308a424246a64 +size 194610 diff --git a/blogs/2016/10/31/git_project_manager.gif b/blogs/2016/10/31/git_project_manager.gif new file mode 100644 index 0000000000000000000000000000000000000000..3407d4f1c7f039a5ca745eaebc83200f7dc8b445 --- /dev/null +++ b/blogs/2016/10/31/git_project_manager.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a49fd4a3f24b2c3c043166db51a6ddc89500d21dbdf932e5ede48baa88c03160 +size 175720 diff --git a/blogs/2016/10/31/js_roundup_2.md b/blogs/2016/10/31/js_roundup_2.md new file mode 100644 index 0000000000000000000000000000000000000000..2663a4cb33a10a9c6c9bc3e9dcc21a604caebed3 --- /dev/null +++ b/blogs/2016/10/31/js_roundup_2.md @@ -0,0 +1,119 @@ +--- +Order: 18 +TOCTitle: JavaScript Extensions Part 2 +PageTitle: Visual Studio Code JavaScript Extensions Part 2 Oct 2016 +MetaDescription: Essential JavaScript extensions for Visual Studio Code. +Date: 2016-10-31 +ShortDescription: Essential JavaScript extensions for Visual Studio Code. +Author: Wade Anderson +--- +# JavaScript Extensions Part 2 + +October 31, 2016 by Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +Visual Studio Code has excellent support for JavaScript out of the box. As with other languages, JavaScript is powered by a language service. The [JavaScript language service](https://github.com/Microsoft/TypeScript/wiki/JavaScript-Language-Service-in-Visual-Studio) is implemented by the TypeScript team, allowing JavaScript developers to leverage the best IntelliSense experience. + +But what other features can you get with VS Code? VS Code has a rich extensibility model and many features are provided through VS Code extensions. This post is a follow up to my [previous post](/blogs/2016/09/14/js_roundup_1.md) about JavaScript extensions. + +> **Tip:** Install any of these extensions by clicking the Extensions View button, typing the name of the extension in the Search box, and clicking **Install**. See more instructions [here](/docs/editor/extension-gallery.md#browse-and-install-extensions). + +## Debugger for Chrome + +Marketplace - [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) + +Publisher - [Microsoft](https://marketplace.visualstudio.com/search?term=publisher%3A%22Microsoft%22&target=VSCode&sortBy=Relevance) + +When you develop for the front end, you might not see the value of an integrated debugger in your editor. You use the browser's debugger right? This is where the Debugger for Chrome extension comes in. This extension lets you debug your JavaScript code in the Google Chrome browser, or any other targets that support the [Chrome Debugging Protocol](https://chromedevtools.github.io/debugger-protocol-viewer/) while staying in VS Code. No more context switching to debug! + +Prefer to debug using a different browser? You can find extensions for [Edge](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-edge) and [Firefox](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-firefox-debug) as well. + +![debugger for chrome image](chrome_debugger.png) + +## Git Project Manager + +Marketplace - [Git Project Manager](https://marketplace.visualstudio.com/items?itemName=felipecaputo.git-project-manager) + +Publisher - [Felipe Caputo](https://marketplace.visualstudio.com/search?term=publisher%3A%22Felipe%20Caputo%22&target=VSCode&sortBy=Relevance) + +Although not necessarily a JavaScript extension, Git Project Manager is a favorite in the VS Code team. This extension scans a directory (or directories) for Git repos and allows you to switch between them easily. + +To use this extension, first install it and then add the following configuration to your `settings.json` file. + +```json +"gitProjectManager.baseProjectsFolders": [ + "/path/to/your/base/project/folders" +] +``` + +![git project manager showcase](git_project_manager.gif) + +## Document This + +Marketplace - [Document This](https://marketplace.visualstudio.com/items?itemName=joelday.docthis) + +Publisher - [Joel Day](https://marketplace.visualstudio.com/search?term=publisher%3A%22Joel%20Day%22&target=VSCode) + +Joel Day has built an exceptionally useful extension for writing JavaScript and TypeScript docs. This extension will automatically generates detailed JSDoc comments for your code. + +![document this](document_this.gif) + +## Beautify + +Marketplace - [Beautify](https://marketplace.visualstudio.com/items?itemName=HookyQR.beautify) + +Publisher - [HookyQR](https://marketplace.visualstudio.com/search?term=publisher%3A%22HookyQR%22&target=VSCode) + +Internally, VS Code uses [js-beautify](https://www.npmjs.com/package/js-beautify). This extension allows you to specify a `.jsbeautifyrc` file to indicate the formatting style for your JavaScript, CSS, Sass, and HTML code. + +You can search the Marketplace for more formatters using the new [Formatters category](https://marketplace.visualstudio.com/search?target=VSCode&category=Formatters&sortBy=Downloads). + +>**Note:** For extension authors, we are working on a blog post for source code formatters best practices. Stay tuned as it will be coming soon. + +## Keymaps for Sublime Text and Atom + +There are two extensions in this section, one for [Atom](https://marketplace.visualstudio.com/items?itemName=ms-vscode.atom-keybindings) and another for [Sublime Text](https://marketplace.visualstudio.com/items?itemName=ms-vscode.sublime-keybindings). If you have used these editors, you have likely memorized their keyboards shortcuts. These extensions bring the keyboard shortcuts from Atom and Sublime Text to VS Code. + +These extensions are in preview because we want your feedback. There are still many shortcuts to include and it is easy for you to add any we may have missed. + +1. Go to the extension's GitHub repository ([Atom](https://github.com/waderyan/vscode-atom-keybindings) and [Sublime Text](https://github.com/Microsoft/vscode-sublime-keybindings)). +2. Open the `package.json` file ([Atom](https://github.com/waderyan/vscode-atom-keybindings/blob/master/package.json) and [Sublime Text](https://github.com/Microsoft/vscode-sublime-keybindings/blob/master/package.json)). +3. Add a JSON object to `contributes.keybindings` section of `package.json` as seen below ([Atom](https://github.com/waderyan/vscode-atom-keybindings/blob/master/package.json#L25) and [Sublime Text](https://github.com/Microsoft/vscode-sublime-keybindings/blob/master/package.json#L25)). +4. Open a pull request. + +```json +{ + "mac": "", + "linux": "", + "command": " +[@waderyan_](https://twitter.com/waderyan_) diff --git a/blogs/2016/11/15/formatters-best-practices.md b/blogs/2016/11/15/formatters-best-practices.md new file mode 100644 index 0000000000000000000000000000000000000000..68a87d4c21d10ee23a9d40fc681a1525b9121190 --- /dev/null +++ b/blogs/2016/11/15/formatters-best-practices.md @@ -0,0 +1,93 @@ +--- +Order: 20 +TOCTitle: Creating a Formatter Extension +PageTitle: Creating a Formatter Extension +MetaDescription: Best practices for creating a Visual Studio Code formatter extension. +Date: 2016-11-21 +ShortDescription: Best practices for creating a Visual Studio Code formatter extension. +Author: Johannes Rieken +--- + +# Creating a Formatter Extension + +November 21, 2016 by Johannes Rieken, [@johannesrieken](https://twitter.com/johannesrieken) + +Since its introduction, the Visual Studio Code extension API has provided support for source code formatters. The first language extensions we built, for example TypeScript, C# and Go, used the formatting API. We wrote this blog to explain the best practices for implementing formatters. + +VS Code's extension API follows a set of guiding principles. The essence of these principles is that VS Code provides the skeleton and extensions provide the "smarts". The common pattern is for VS Code to provide the UI around a feature and the extensions provide the necessary data to make it shine. + +The core benefit of using the extension API for implementing a formatter comes from the exposure of the **Format Document** and **Format Selection** actions. These actions are available in the editor context menu, bound to keyboard shortcuts, and visible in the **Command Palette**. Using the API leads to a consistent user experience across all formatter extensions. + +## The Formatting API + +The code snippets below show what to do and what not to do when implementing a formatter. The best practice is to use the formatting API and not create a new action, such as "Format Foo File." The full extension example can be found on [GitHub](https://github.com/jrieken/vscode-formatter-sample). + +```typescript +// 👎 formatter implemented as separate command +vscode.commands.registerCommand('extension.format-foo', () => { + const {activeTextEditor} = vscode.window; + + if (activeTextEditor && activeTextEditor.document.languageId === 'foo-lang') { + const {document} = activeTextEditor; + const firstLine = document.lineAt(0); + + if (firstLine.text !== '42') { + const edit = new vscode.WorkspaceEdit(); + edit.insert(document.uri, firstLine.range.start, '42\n'); + + return vscode.workspace.applyEdit(edit) + } + } +}); + + +// 👍 formatter implemented using API +vscode.languages.registerDocumentFormattingEditProvider('foo-lang', { + provideDocumentFormattingEdits(document: vscode.TextDocument): vscode.TextEdit[] { + + const firstLine = document.lineAt(0); + if (firstLine.text !== '42') { + return [vscode.TextEdit.insert(firstLine.range.start, '42\n')]; + } + } +}); +``` + +Recently, we added the "Format on Save" feature. An extension properly implementing the formatting API supports this feature without any new code. + +> Tip: To take advantage of this, a formatting extension needs to be registered using the [registerDocumentFormattingEditProvider](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.d.ts#L4172) API call. + +## Multiple Formatters + +A common misunderstanding is that when contributing a formatter, you must support all programming languages. When an extension registers as a formatter with [registerDocumentFormattingEditProvider](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.d.ts#L4172), it indicates with a [DocumentSelector](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.d.ts#L1501) which programming languages it supports. With that information, the editor can enable the formatting actions when for example, an HTML document is open. Likewise, the editor will disable the formatting actions when displaying documents for which no formatter is registered. + +What happens when there are multiple formatters for one language? This can be a problem when different formatters' actions contradict. In the October release, we added settings to enable or disable the default formatters that ship with VS Code. The best practice is for extension authors to add a similar setting as what we did in VS Code as shown below. + +```json +"html.format.enable": true, +"javascript.format.enable": true, +"typescript.format.enable": true, +"json.format.enable": true +``` + +An extension adds settings through the [contributes.configuration](/docs/extensionAPI/extension-points.md#contributesconfiguration) extension point. + +## Formatters in the Marketplace + +Last, we want to bring more awareness to formatters and have added a new ["Formatters" category](https://marketplace.visualstudio.com/search?target=VSCode&category=Formatters&sortBy=Downloads) to the Marketplace. We have seeded it with popular formatting extensions and invite formatter authors to add theirs as well. You can also use [extension packs](/updates/v1_7#_extension-packs) to bundle a formatter extension with other extensions for your favorite language. + +## Summary + +To summarize, an extension that implements the formatting extension API properly will do the following : + +1. Register formatters via [registerDocumentFormattingEditProvider](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.d.ts#L4172). +2. Implement the formatting logic per the [DocumentFormattingEditProvider interface](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.d.ts#L2143). +3. Have a setting to enable / disable the formatter. +4. Add the "Formatters" category to the extension manifest. + +We are not done with the feature work for formatters. "Format on Paste", "Format Files in Folder" and more are on our roadmap and we are happily awaiting more of your feedback and ideas. + +[#HappyCoding](https://twitter.com/hashtag/HappyCoding?src=hash) + +Johannes Rieken, VS Code Team Member
+[@johannesrieken](https://twitter.com/johannesrieken) \ No newline at end of file diff --git a/blogs/2016/11/3/rollback.md b/blogs/2016/11/3/rollback.md new file mode 100644 index 0000000000000000000000000000000000000000..e141025ff0aaae1dbe673759c8c1dceae6d22020 --- /dev/null +++ b/blogs/2016/11/3/rollback.md @@ -0,0 +1,53 @@ +--- +Order: +TOCTitle: 1.7 Rollback Incident Report +PageTitle: Visual Studio Code 1.7 Rollback Incident Report +MetaDescription: Visual Studio Code 1.7 Rollback Incident Report +Date: 2016-11-03 +ShortDescription: Visual Studio Code 1.7 Rollback Incident Report +Author: Wade Anderson +--- + +# 1.7 Rollback Incident Report + +November 3, 2016 by Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +Last night Wednesday November 2nd, we rolled back the 1.7 release of Visual Studio Code to 1.6.1. If you had upgraded to 1.7, you would have been prompted to update back to 1.6.1. This morning we implemented a mitigation fix and created a new release and you should now be on VS Code 1.7.1. If you are not sure what version you are on, you can [find the version information](/docs/supporting/faq.md#how-do-i-find-what-version-of-vs-code-i-am-using) in the About dialog. + +We apologize for the inconvenience these updates caused and want to explain the events that took place and the steps we're taking to ensure you have a great experience with VS Code. + +## Automatic Type Acquisition + +In VS Code 1.7, we released a featured called "Automatic Type Acquisition" (ATA). The purpose of ATA is to improve the JavaScript IntelliSense experience. + +VS Code uses the TypeScript language service to provide IntelliSense for JavaScript. The TypeScript language service uses special files called type declaration files (also known as typings files), which are published on npm under the [@types scope](https://www.npmjs.com/~types). In the past, you had to manually install type declaration files to light up IntelliSense for the dependencies in `package.json`. We know this isn't an easy chore so we teamed up with the TypeScript team to develop ATA. + +A TypeScript language service that has ATA enabled watches your `package.json` files and automatically installs the type declaration files of all dependencies in a cache on your file system. It does the same when it finds references to well-known client-side libraries. + +After enabling this feature on Insiders builds for two weeks, we felt it proved useful for users and decided to ship ATA to everyone in VS Code 1.7. + +## What happened? + +**Nov 2 at ~1:57 pm PST** We released VS Code 1.7. The team in Zurich went to bed and the Redmond team started on our plans for 1.8. + +**Nov 2 at ~4:12 pm PST** We were contacted by npm. They were seeing a huge spike in registry activity from clients attempting to access non-existent packages under the `@types` scope. At its peak, these requests accounted for roughly 10% of all traffic ([Fun fact](https://news.ycombinator.com/item?id=12861093): VS Code users were sending approximately the same amount of requests npm sees from the country of India) and briefly overwhelmed their service. + +The npm dev ops acted quickly to mitigate the un-intentional DDoS and diagnosed the issue as coming from the VS Code 1.7 release. The key issue was a flood of requests for non-existent packages, caused by the following algorithm: + +1. The TypeScript language server checks the modules listed in `package.json` against its application cache. +2. For each module not in the application cache, the TypeScript language server makes a request to npm requesting `@types/{module}`. +3. Modules that do exist are added to the application cache. +4. Anticipating that new type declaration files will be added to `@types` scope, modules that don't exist are requested each time a project or folder is opened, which causes npm to respond with a 404. + +Given the number of modules that do not exist under the `@types` scope, a large volume of 404's briefly impacted npm's availability. + +**Nov 2 at ~5:45 pm PST** With proper context and at the request of npm, we took down the 1.7 release and moved users back VS Code 1.6.1. We updated the website with the facts we had and rolled up our sleeves to analyze the best next steps. + +## Going forward + +You should have been prompted to install VS Code 1.7.1. This release has ATA disabled, however all other 1.7 features are available to use. Over the next few days, we will work with the TypeScript team on a satisfactory fix for ATA (one was started last night in this [PR](https://github.com/Microsoft/TypeScript/pull/12014)) and we will notify you when this update is available. + +[#HappyCoding](https://twitter.com/hashtag/HappyCoding?src=hash) + +Wade Anderson, VS Code Team Member
+[@waderyan_](https://twitter.com/waderyan_) \ No newline at end of file diff --git a/blogs/2016/11/30/hot-exit-in-insiders.md b/blogs/2016/11/30/hot-exit-in-insiders.md new file mode 100644 index 0000000000000000000000000000000000000000..25f8aee9dd611675f4cf2424ca3b6c4a33d2f321 --- /dev/null +++ b/blogs/2016/11/30/hot-exit-in-insiders.md @@ -0,0 +1,43 @@ +--- +Order: 21 +TOCTitle: Hot Exit Comes to Insiders +PageTitle: Hot Exit Comes to Insiders +MetaDescription: Unsaved changes are now remembered between Visual Studio Code sessions. +MetaSocialImage: /assets/blogs/2016/11/30/opengraph_insiders.png +Date: 2016-11-30 +ShortDescription: Unsaved changes are now remembered between Visual Studio Code sessions. +Author: Daniel Imms +--- + +# Hot Exit Comes to Insiders + +November 30, 2016 by Daniel Imms, [@Tyriar](https://twitter.com/Tyriar) + +The ability to have Visual Studio Code remember unsaved changes when you exit (hot exit) has been a long requested feature, in fact it's currently [number #3](https://github.com/Microsoft/vscode/issues/101) in terms of 👍 reactions on GitHub. We've been working on an implementation for some time and it is now enabled by default in the Insiders build! + +## Initial design + +We initially considered tying backups to an opened folder so that once VS Code was closed, that same folder would have to be opened again in order to trigger the hot exit restore. The main issue with this approach was that backups could potentially go "missing"; the backups are still around but the user may have forgotten which folder they were in when they made the changes. + +## Restricting to entire application shutdown + +It was due to this fear of having backups persisted but not be discoverable that we decided to add a restriction to when a hot exit occurs: Hot exit will only occur when *all* VS Code windows are being closed, or in the case of Mac, the application is quit (`kbstyle(Cmd+Q)`). + +While this may seem restricting at first, particularly when you frequently work on multiple folders, the great thing is that *all* of the workspaces with backups will be presented when you relaunch VS Code and so there is no ambiguity as to what else could be backed up. + +The important exception to this restriction is that when a window is reloaded then hot exit will always trigger. This means no more annoying Save dialog when installing extensions! + +## Crash protection + +The way hot exit works is to periodically make backups of unsaved files. If VS Code happens to crash, a backup restore will occur the next time the folder is opened. + +## Looking forward + +Hot exit will be coming to the Stable build in the November/December update (1.8.0). + +After that, we want to look into how best to loosen the restrictions for when a hot exit is triggered while at the same time ensuring backups don't go missing ([#15467](https://github.com/Microsoft/vscode/issues/15467)). The solution to this largely depends on how VS Code will handle multiple folder workspaces ([#396](https://github.com/Microsoft/vscode/issues/396)). + +[#HappyCoding](https://twitter.com/hashtag/HappyCoding?src=hash) + +Daniel Imms, VS Code Team Member
+[@Tyriar](https://twitter.com/Tyriar) diff --git a/blogs/2016/11/30/opengraph_insiders.png b/blogs/2016/11/30/opengraph_insiders.png new file mode 100644 index 0000000000000000000000000000000000000000..42b3b4886d81d05b96b0a1c6c6666c70f151f759 Binary files /dev/null and b/blogs/2016/11/30/opengraph_insiders.png differ diff --git a/blogs/2016/12/12/roundup-customize.md b/blogs/2016/12/12/roundup-customize.md new file mode 100644 index 0000000000000000000000000000000000000000..711ba41d510574225863495df192cee372d7753f --- /dev/null +++ b/blogs/2016/12/12/roundup-customize.md @@ -0,0 +1,89 @@ +--- +Order: 22 +TOCTitle: Customize VS Code Extension Roundup +PageTitle: Customize Visual Studio Code Extension Roundup +MetaDescription: Extensions to customize Visual Studio Code. +Date: 2016-12-12 +ShortDescription: Extensions to customize Visual Studio Code. +Author: Wade Anderson +--- + +# Customize VS Code Extension Roundup + +December 12, 2016 - Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +You can customize Visual Studio Code in many ways. Install a new theme, add a snippet pack, or tweak your settings and keyboard shortcuts. We built VS Code to be flexible so you can make it work the way you do. You can install an extension from the VS Code [Marketplace](https://marketplace.visualstudio.com/vscode) or create your own (see [here](https://code.visualstudio.com/docs/extensions/overview) to get started writing an extension in JavaScript or TypeScript). In this blog, I want to highlight a few of my favorite extensions for customizing VS Code. + +> **Tip:** Do you miss the keyboard shortcuts from Atom, Sublime Text, or Visual Studio? You can install a Keymap extension today to use those keyboard shortcuts in VS Code. See [the full list of keymap extensions](https://marketplace.visualstudio.com/search?target=vscode&category=Keymaps&sortBy=Downloads) in the Marketplace. + +## Settings Sync + +Marketplace - [Visual Studio Code Settings Sync](https://marketplace.visualstudio.com/items?itemName=Shan.code-settings-sync) + +Publisher - [Shan Khan](https://marketplace.visualstudio.com/search?term=publisher%3A%22Shan%20Khan%22&target=VSCode&sortBy=Relevance) + +Do you use VS Code on multiple machines and wish you could easily share settings? Even using VS Code in a VM on the same machine will make it so your settings, snippets, etc. aren't the same. This extension solves this synchronization problem and is one of the highest rated in the Marketplace. The extension uses a private Gist on GitHub to share your VS Code settings, snippets, keybindings, etc across different machines. You can also make the Gist public to share your settings with others. + +![setting sync](settings_sync.png) + +## Themes Galore + +Color themes are important. When you are staring at your editor for hours each day, you want to look at something nice! I find myself changing my theme regularly to mix things up (in fact, that would be a fun extension for someone to make - an extension that changes the theme on a regular interval). There are hundreds of color themes in the VS Code Marketplace to install. You can preview your installed themes in VS Code by **File** > **Preferences** > **Color Theme** or by opening the **Command Palette** and typing "theme". + +Some of my favorite themes are: + +- [Sublime Material Theme](https://marketplace.visualstudio.com/items?itemName=jprestidge.theme-material-theme) from [Jarvis Prestidge](https://marketplace.visualstudio.com/search?term=publisher%3A%22Jarvis%20Prestidge%22&target=VSCode&sortBy=Relevance) +- [Flatland Monokai Theme](https://marketplace.visualstudio.com/items?itemName=gerane.Theme-FlatlandMonokai) from [gerane](https://marketplace.visualstudio.com/search?term=publisher%3A%22gerane%22&target=VSCode&sortBy=Relevance) +- [Hopscotch (Official)](https://marketplace.visualstudio.com/items?itemName=idleberg.hopscotch) from [idleberg](https://marketplace.visualstudio.com/search?term=publisher%3A%22idleberg%22&target=VSCode&sortBy=Relevance) +- [One Monokai Theme](https://marketplace.visualstudio.com/items?itemName=azemoh.one-monokai) from [Joshua Azemoh](https://marketplace.visualstudio.com/search?term=publisher%3A%22Joshua%20Azemoh%22&target=VSCode&sortBy=Relevance) + +![animation showing my favorite themes](theme-preview.gif) + +> **Tip:** Color themes are tagged `color-theme` on their Marketplace page. + +Want to create your own theme? See the [documentation](https://code.visualstudio.com/docs/extensionAPI/extension-points#_contributesthemes) to get started. + +VS Code also supports [File Icon](https://code.visualstudio.com/docs/getstarted/themes#_select-an-icon-theme) themes to add images to files and folders in the UI. You can preview your installed File Icon themes in VS Code by **File** > **Preferences** > **File Icon Theme** or by opening the **Command Palette** and typing "file icon". + +Here are two File Icon themes I really like: + +- [Material Icon Theme](https://marketplace.visualstudio.com/items?itemName=PKief.material-icon-theme) from [Philipp Kief](https://marketplace.visualstudio.com/search?term=publisher%3A%22Philipp%20Kief%22&target=VSCode&sortBy=Relevance) +- [Nomo Dark Icon Theme](https://marketplace.visualstudio.com/items?itemName=be5invis.vscode-icontheme-nomo-dark) from [be5invis](https://marketplace.visualstudio.com/search?term=publisher%3A%22be5invis%22&target=VSCode&sortBy=Relevance) + +> **Tip:** File Icon themes are tagged `icon-theme`. + +## Snippets Aplenty + +Do you use snippets while writing code? Many snippets come built into VS Code and are shown in the IntelliSense suggest window while you type. + + + +When you start using a new library or framework, check the Marketplace to see if there is a snippet pack for it. There are snippet packs for many popular JavaScript frameworks. + +- [Bootstrap 3](https://marketplace.visualstudio.com/items?itemName=wcwhitehead.bootstrap-3-snippets) from [William Whitehead](https://marketplace.visualstudio.com/search?term=publisher%3A%22William%20Whitehead%22&target=VSCode&sortBy=Relevance) +- [Angular 2](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular2) from [John Papa](https://marketplace.visualstudio.com/search?term=publisher%3A%22johnpapa%22&target=VSCode&sortBy=Relevance) +- [jQuery](https://marketplace.visualstudio.com/items?itemName=donjayamanne.jquerysnippets) from [Don Jayamanne](https://marketplace.visualstudio.com/search?term=publisher%3A%22Don%20Jayamanne%22&target=VSCode&sortBy=Relevance) + +Many language extensions come with snippets included. + +- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) from [Microsoft](https://marketplace.visualstudio.com/search?term=publisher%3A%22Microsoft%22&target=VSCode&sortBy=Relevance) +- [Power Shell](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell) from [Microsoft](https://marketplace.visualstudio.com/search?term=publisher%3A%22Microsoft%22&target=VSCode&sortBy=Relevance) +- [Ruby](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby) from [Peng Lv](https://marketplace.visualstudio.com/search?term=publisher%3A%22Peng%20Lv%22&target=VSCode&sortBy=Relevance) +- [C#](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp) from [Microsoft](https://marketplace.visualstudio.com/search?term=publisher%3A%22Microsoft%22&target=VSCode&sortBy=Relevance) +- [Elm](https://marketplace.visualstudio.com/items?itemName=sbrink.elm) from [Sascha Brink](https://marketplace.visualstudio.com/search?term=publisher%3A%22Sascha%20Brink%22&target=VSCode&sortBy=Relevance) + +Want to make your own snippet pack? See the documentation for [how to create a snippet pack extension](https://code.visualstudio.com/docs/extensionAPI/language-support#_source-code-snippets). + +> **Tip:** You can search for extensions by category or tag in the Extensions view search box, using "category:{category name}" or "tag:{tag name}". + +## Want to see your extension featured? + +Have other extensions you like or want to see your extension in the next roundup? Ping me on [Twitter!](https://twitter.com/waderyan_). + +Wade Anderson, VS Code Team Member +[@waderyan_](https://twitter.com/waderyan_) + + + diff --git a/blogs/2016/12/12/settings_sync.png b/blogs/2016/12/12/settings_sync.png new file mode 100644 index 0000000000000000000000000000000000000000..5228cb635491927b6c48124eb99f1e2e53b56685 Binary files /dev/null and b/blogs/2016/12/12/settings_sync.png differ diff --git a/blogs/2016/12/12/theme-preview.gif b/blogs/2016/12/12/theme-preview.gif new file mode 100644 index 0000000000000000000000000000000000000000..400b0b7fbc915168d8b6567a2469959de36de48e --- /dev/null +++ b/blogs/2016/12/12/theme-preview.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6471d7577ebfa0e656ee091e1717fb8025477bce5ddf9c4aae8d3f7a9f032500 +size 674264 diff --git a/blogs/2017/01/15/AllResources.png b/blogs/2017/01/15/AllResources.png new file mode 100644 index 0000000000000000000000000000000000000000..a3e4c4556a6ab1165488a970805016849f3889a3 Binary files /dev/null and b/blogs/2017/01/15/AllResources.png differ diff --git a/blogs/2017/01/15/AppSettings.png b/blogs/2017/01/15/AppSettings.png new file mode 100644 index 0000000000000000000000000000000000000000..2a99eb6277f1eacba47a22b3141718d24e4a2429 --- /dev/null +++ b/blogs/2017/01/15/AppSettings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:aa5dedf53a520016acbe5cd479583644acec8397f574671dd9cc03be9c04e130 +size 105641 diff --git a/blogs/2017/01/15/AzurePortal.png b/blogs/2017/01/15/AzurePortal.png new file mode 100644 index 0000000000000000000000000000000000000000..c347118c2a2ed3957add7b7cade1094f905c1d95 --- /dev/null +++ b/blogs/2017/01/15/AzurePortal.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9d0927c93d3757f49ad0fbdf6997dd1e7055455d5d2e80f870c950bcb1114b83 +size 177025 diff --git a/blogs/2017/01/15/Breakpoint.png b/blogs/2017/01/15/Breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..8256988f3ec83c7f471a3e20011b772aa0deb1f0 Binary files /dev/null and b/blogs/2017/01/15/Breakpoint.png differ diff --git a/blogs/2017/01/15/BrowseApp.png b/blogs/2017/01/15/BrowseApp.png new file mode 100644 index 0000000000000000000000000000000000000000..eb3b61e1d0969b10b6517984699486b1c9c18753 Binary files /dev/null and b/blogs/2017/01/15/BrowseApp.png differ diff --git a/blogs/2017/01/15/Chrome.png b/blogs/2017/01/15/Chrome.png new file mode 100644 index 0000000000000000000000000000000000000000..a62cb78fe2dd2f216cf028db62e141d17698e6a1 Binary files /dev/null and b/blogs/2017/01/15/Chrome.png differ diff --git a/blogs/2017/01/15/ChromePause.png b/blogs/2017/01/15/ChromePause.png new file mode 100644 index 0000000000000000000000000000000000000000..adbb868bd72428e1e08ba2b378eeff533bc2c2af --- /dev/null +++ b/blogs/2017/01/15/ChromePause.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:67cfa05e27104bf793b8a2f52b49b3cddf788a4e5367611391ea184e73c9a146 +size 168613 diff --git a/blogs/2017/01/15/CodePeek.png b/blogs/2017/01/15/CodePeek.png new file mode 100644 index 0000000000000000000000000000000000000000..7cb6707c6c5232bf665bd2e6beaad8e7cd277abe Binary files /dev/null and b/blogs/2017/01/15/CodePeek.png differ diff --git a/blogs/2017/01/15/ConnectionString.png b/blogs/2017/01/15/ConnectionString.png new file mode 100644 index 0000000000000000000000000000000000000000..348dded5676d83de83b5e016391f32a33d9d1de6 Binary files /dev/null and b/blogs/2017/01/15/ConnectionString.png differ diff --git a/blogs/2017/01/15/Console.png b/blogs/2017/01/15/Console.png new file mode 100644 index 0000000000000000000000000000000000000000..f11a31ea1abaf625f40f87f3d756d5c7cef6aae5 Binary files /dev/null and b/blogs/2017/01/15/Console.png differ diff --git a/blogs/2017/01/15/ConsoleCode.png b/blogs/2017/01/15/ConsoleCode.png new file mode 100644 index 0000000000000000000000000000000000000000..9c8f0e64f47efb76ae38c21743559580651899b3 Binary files /dev/null and b/blogs/2017/01/15/ConsoleCode.png differ diff --git a/blogs/2017/01/15/CreateDocDB.png b/blogs/2017/01/15/CreateDocDB.png new file mode 100644 index 0000000000000000000000000000000000000000..c950077e0369fcb9d9b56865df60c6b07e0f69f3 --- /dev/null +++ b/blogs/2017/01/15/CreateDocDB.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a18f3bb23a9cc92ce8e9016b6305c28cde78f1cf353c689809b72c6676d09dcb +size 124264 diff --git a/blogs/2017/01/15/DebugConfig.png b/blogs/2017/01/15/DebugConfig.png new file mode 100644 index 0000000000000000000000000000000000000000..844d4c3edea728432c37c945a3e72d94b325dec2 Binary files /dev/null and b/blogs/2017/01/15/DebugConfig.png differ diff --git a/blogs/2017/01/15/Debugger.png b/blogs/2017/01/15/Debugger.png new file mode 100644 index 0000000000000000000000000000000000000000..7396507a482b0e1c7963f4b93555823ba03671f2 --- /dev/null +++ b/blogs/2017/01/15/Debugger.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a7442ed1b696e9b7248b989deb68d77b932f45764e16f49a52684e1a22ec996b +size 196793 diff --git a/blogs/2017/01/15/DocDBCreate.png b/blogs/2017/01/15/DocDBCreate.png new file mode 100644 index 0000000000000000000000000000000000000000..874e840a945f71dc5012595c837f48f87acc6cdf Binary files /dev/null and b/blogs/2017/01/15/DocDBCreate.png differ diff --git a/blogs/2017/01/15/DocDBScale.png b/blogs/2017/01/15/DocDBScale.png new file mode 100644 index 0000000000000000000000000000000000000000..b4403ce7b59414042853fb14ccc0a58266472639 Binary files /dev/null and b/blogs/2017/01/15/DocDBScale.png differ diff --git a/blogs/2017/01/15/DockerBuild.png b/blogs/2017/01/15/DockerBuild.png new file mode 100644 index 0000000000000000000000000000000000000000..3e98e68c83cc5c1da886b88bfd60422033bebadf Binary files /dev/null and b/blogs/2017/01/15/DockerBuild.png differ diff --git a/blogs/2017/01/15/DockerCommands.png b/blogs/2017/01/15/DockerCommands.png new file mode 100644 index 0000000000000000000000000000000000000000..35ea0077f63b32e80d52f190a49a11fbd9b4d48c Binary files /dev/null and b/blogs/2017/01/15/DockerCommands.png differ diff --git a/blogs/2017/01/15/DockerCompletion.png b/blogs/2017/01/15/DockerCompletion.png new file mode 100644 index 0000000000000000000000000000000000000000..29fb1d496104c4aa99dddcd505ebfc2772213002 Binary files /dev/null and b/blogs/2017/01/15/DockerCompletion.png differ diff --git a/blogs/2017/01/15/DockerSearch.png b/blogs/2017/01/15/DockerSearch.png new file mode 100644 index 0000000000000000000000000000000000000000..100ba8bf77e8b6b49dd70b607bfb0c7404267a74 Binary files /dev/null and b/blogs/2017/01/15/DockerSearch.png differ diff --git a/blogs/2017/01/15/Dockerfile.png b/blogs/2017/01/15/Dockerfile.png new file mode 100644 index 0000000000000000000000000000000000000000..ef2c0748da738f1546095996abf65175b8224267 --- /dev/null +++ b/blogs/2017/01/15/Dockerfile.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:efd542646f9b012dadc83011990f3f94f32f364f4dee3a2197ddb486f9277463 +size 101520 diff --git a/blogs/2017/01/15/Explorer.png b/blogs/2017/01/15/Explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..8ddfb49e2e025ee6159b49c22949d3b28599e82d Binary files /dev/null and b/blogs/2017/01/15/Explorer.png differ diff --git a/blogs/2017/01/15/FilePicker.png b/blogs/2017/01/15/FilePicker.png new file mode 100644 index 0000000000000000000000000000000000000000..d4d4e85c45ba7e1ec02bc54a96086cf0abbd45bb Binary files /dev/null and b/blogs/2017/01/15/FilePicker.png differ diff --git a/blogs/2017/01/15/FinishedDemo.png b/blogs/2017/01/15/FinishedDemo.png new file mode 100644 index 0000000000000000000000000000000000000000..e33c2f78ee3137f2bcb4cf69387f43d7ba726bbb Binary files /dev/null and b/blogs/2017/01/15/FinishedDemo.png differ diff --git a/blogs/2017/01/15/FullStackProfile.png b/blogs/2017/01/15/FullStackProfile.png new file mode 100644 index 0000000000000000000000000000000000000000..4fd4283d80d17a765e86821421575af604ec5701 Binary files /dev/null and b/blogs/2017/01/15/FullStackProfile.png differ diff --git a/blogs/2017/01/15/Git.png b/blogs/2017/01/15/Git.png new file mode 100644 index 0000000000000000000000000000000000000000..d3bed0a295248e21a0f75b5b883f50ea294d67f3 Binary files /dev/null and b/blogs/2017/01/15/Git.png differ diff --git a/blogs/2017/01/15/GitClone.png b/blogs/2017/01/15/GitClone.png new file mode 100644 index 0000000000000000000000000000000000000000..96dc46730150c199f87e688b591bd1809052df84 Binary files /dev/null and b/blogs/2017/01/15/GitClone.png differ diff --git a/blogs/2017/01/15/GitOutput.png b/blogs/2017/01/15/GitOutput.png new file mode 100644 index 0000000000000000000000000000000000000000..fda229d73949b464fdc7664d2ae84332b737826c Binary files /dev/null and b/blogs/2017/01/15/GitOutput.png differ diff --git a/blogs/2017/01/15/HoverHelp.png b/blogs/2017/01/15/HoverHelp.png new file mode 100644 index 0000000000000000000000000000000000000000..643a0d5f77971fab42df8df229aefde1a20d46ca Binary files /dev/null and b/blogs/2017/01/15/HoverHelp.png differ diff --git a/blogs/2017/01/15/LaunchJson.png b/blogs/2017/01/15/LaunchJson.png new file mode 100644 index 0000000000000000000000000000000000000000..db1f425cc23a395e06de75213c33de1391f5391f Binary files /dev/null and b/blogs/2017/01/15/LaunchJson.png differ diff --git a/blogs/2017/01/15/Mongoose.png b/blogs/2017/01/15/Mongoose.png new file mode 100644 index 0000000000000000000000000000000000000000..165d3fb8a0230c9494eb357855933779c46c6c2b Binary files /dev/null and b/blogs/2017/01/15/Mongoose.png differ diff --git a/blogs/2017/01/15/ProcessEnv.png b/blogs/2017/01/15/ProcessEnv.png new file mode 100644 index 0000000000000000000000000000000000000000..27b5942e883862a6a9f3496ecb6f103847bbdb51 Binary files /dev/null and b/blogs/2017/01/15/ProcessEnv.png differ diff --git a/blogs/2017/01/15/Terminal.png b/blogs/2017/01/15/Terminal.png new file mode 100644 index 0000000000000000000000000000000000000000..abba7952463390611e4e46687a1c6edebcedcb0f Binary files /dev/null and b/blogs/2017/01/15/Terminal.png differ diff --git a/blogs/2017/01/15/Todo.png b/blogs/2017/01/15/Todo.png new file mode 100644 index 0000000000000000000000000000000000000000..0e552d0f70245956ce6c26598ec9095b81e61b93 Binary files /dev/null and b/blogs/2017/01/15/Todo.png differ diff --git a/blogs/2017/01/15/WordHighlight.png b/blogs/2017/01/15/WordHighlight.png new file mode 100644 index 0000000000000000000000000000000000000000..19fb5b0a80bf7af07878d775fc55b3a55cf53183 Binary files /dev/null and b/blogs/2017/01/15/WordHighlight.png differ diff --git a/blogs/2017/01/15/connect-nina-e2e.md b/blogs/2017/01/15/connect-nina-e2e.md new file mode 100644 index 0000000000000000000000000000000000000000..74f5bda196f6457a7402ba6a46737445ab76f8d8 --- /dev/null +++ b/blogs/2017/01/15/connect-nina-e2e.md @@ -0,0 +1,399 @@ +--- +Order: 23 +TOCTitle: Node.js Development with Visual Studio Code and Azure +PageTitle: Node.js Development with Visual Studio Code and Azure +MetaDescription: Node.js Development with Visual Studio Code and Azure +Date: 2017-01-15 +ShortDescription: Node.js Development with Visual Studio Code and Azure +Author: Jonathan Carter +--- +# Node.js Development with Visual Studio Code and Azure + +January, 4 2017 - Jonathan Carter, [@lostintangent](https://twitter.com/LostInTangent) + +Between Visual Studio Code and Azure, we're trying to contribute to simplifying and improving the overall developer experience of building, debugging and deploying Node.js applications. At [Node Interactive North America 2016](events.linuxfoundation.org/events/node-interactive), I was excited to be able to demo some of the work we've been doing recently based on community feedback, and this article tries to capture that workflow for folks who are interested in trying it out and/or are looking for a little more detail than I was able to cover in my talk. + +The demo makes use of a simple todo app created by and published by [Scotch.io](https://scotch.io/tutorials/creating-a-single-page-todo-app-with-node-and-angular). It is a single-page MEAN application, and therefore, uses MongoDB as its database, Node/Express for the REST API/web server and Angular.js 1.x for the front-end UI. Use the following ToC to jump to particular sections of interest, otherwise, continue reading ahead. + +* [Prerequisites](#prerequisites) +* [Project Setup](#project-setup) +* [Integrated Terminal](#integrated-terminal) +* [Integrated Git version control](#integrated-git-version-control) +* [Project / Code navigation](#project--code-navigation) +* [Auto-completion](#auto-completion) +* [Running The App](#running-the-app) +* [Integrated Debugging](#debugging) +* [Full Stack Debugging](#full-stack-debugging) +* [Dockerizing Your App](#dockerizing-your-app) +* [Deploying Your App](#deploying-your-app) +* [Using DocumentDB](#using-documentdb) +* [Clean-up](#clean-up) +* [Conclusion](#conclusion) + +## Prerequisites + +In order to effectively run through this demo, you'll need to have the following software installed: + +1. Visual Studio Code Insiders build, which you can download [here](https://code.visualstudio.com/insiders). You don't technically need the Insiders build, however, I would encourage everyone to use it since it provides access to the latest bug fixes/feature enhancements (just like Chrome Canary builds), and is the same build that the VS Code team uses. + +2. Docker, which can be downloaded [here](https://www.docker.com/products/docker). Additionally, you will need to have a [DockerHub](https://hub.docker.com/) account in order to publish the Docker images that will be created in the walkthrough. + +3. Azure CLI (>=`v0.1.0b11`), which provides installation instructions [here](https://github.com/Azure/azure-cli#interactive-install-script). Additionally, you will need an Azure account, and be logged in with the Azure CLI by running `az login` and following the interactive login. + +4. Yarn, which provides installation instructions [here](https://yarnpkg.com/en/docs/install). This isn't technically required, however, it's used in place of the NPM client below. I'd recommend it! + +Additionally, since the demo app uses MongoDB, you need to have a locally running MongoDB instance, which is listening on the standard `27017` port. The simplest way to achieve this is by running the following command after Docker is installed: `docker run -it -p 27017:27017 mongo`. + +## Project Setup + +To get started, we need to grab the todo sample project so we can start playing around with it. To do this, perform the following steps: + +1. Open up Visual Studio Code, and type `F1` to bring up the **Command Palette** (or alternatively, select `Command Palette...` from the `View` menu). + +2. Type `gitcl` to find the `Git: Clone` command and hit `ENTER`. + + + +> Note: The VS Code **Command Palette** supports "fuzzy search", which allows you to type fewer keystrokes to find commonly used commands. + +3. Enter `https://github.com/scotch-io/node-todo` into the prompt and hit `ENTER`. + +4. Select the folder you'd like to clone the project into, or create a new one (e.g. called `Todos`). At this point, VS Code will clone the repo, and launch a new workspace that is rooted at the newly cloned project. + + + +Alternatively, you could use the Git CLI to clone the sample repo, however, this exercise helps illustrate some of the productivity enhancers that VS Code provides by means of the command palette. I'd encourage you to hit `F1` and browse the various commands it (and any installed extensions) provides, in order to identify what else you can do. + +## Integrated Terminal + +Since this is a Node.js project, the first thing we need to do is ensure that all of its dependencies are installed from NPM, since they weren't checked into the Git repo. You can perform this step from within your standard terminal (I would recommend [Hyper](https://hyper.is/)!), or, if you prefer, you can also bring up the VS Code integrated terminal by pressing `` CTRL+` `` and then running either `npm install` or `yarn`, depending on which NPM client you prefer. I like Yarn since it's very fast and provides some great workflow improvements, so I'd recommend checking it out if you haven't already. + + + +Since VS Code wants to fit naturally into your existing workflow, it's up to you to decide if and when the integrated terminal is useful. I find that if I'm running VS Code full-screen (especially with the new Zen mode!), it's nice to be able to use the integrated terminal for simple/one-off commands. Whereas if I'm doing something more "sophisticated", I'll just switch to a full-screen version of Hyper. Choice and flexibility is key here. + +## Integrated Git version control + +Installing the app's dependencies via Yarn resulted in a `yarn.lock` file being generated, which provides a predictable way to re-acquire the exact same dependencies in the future, without any surprises in either CI builds, production deployments or other developer's machines. + +It is encouraged that this file be checked into source control, and to do this, you can easily switch to the integrated Git tab in VS Code (the one with the Git logo), and notice the newly added file. You can type in a commit message, and type `CMD+Enter` (or click the checkmark icon) in order to stage/commit the change locally. + + + +Behind the scenes, this is simply automating the same Git CLI commands you would have run manually, so once again, it's up to you to decide whether the integration in VS Code works for you or not. If you're curious, you can bring up the Git output window by clicking the `...` menu item and selecting `Show Git Output`. This will display all of the underlying Git activity that VS Code is performing on your behalf. + + + +## Project / Code navigation + +In order to orient ourselves within the codebase, let's play around with some examples of some of the navigation capabilities that VS Code provides: + +1. Type `CMD+P` and enter `.js`, which lets you see all of the JavaScript/JSON files in the project, along with the directory they're within. Once again, this dialog supports the same "fuzzy search" as the command palette, so it's pretty flexible. + +
+ +2. Select `server.js`, which is the startup script for the app. + +3. Hover over the `database` variable that is imported on line 6 in order to see its "type". This ability to quickly inspect variables/modules/types within a file can come in very handy, especially since we tend to spend more time reading/understanding code than writing it! + +
+ +4. Simply placing your cursor within the span of the name `database`, allows you to quickly see all other references to it within the same file, and right-clicking and selecting **Peek References** allows you to see uses of it project wide. + + + +5. Beyond quickly inspecting variable types on hover, you can also inspect the definition of a variable, even if it's in another file! For example, right-click on `database.localUrl` on line 12, and select `Peek Definition`, which lets us quickly see how the app is configured to connect to MongoDB by default. + + + +Cloud-native, [twelve-factor apps](https://12factor.net/) don't hardcode configuration like this, and therefore, it would be better to set our MongoDB connection string via an environment variable, which can easily be changed per deployment/environment. Let's make that change! + +## Auto-completion + +Auto-completion can provide huge productivity enhancements when writing/exploring code, since it prevents you from needing to keep referencing documentation or worrying about API typos. For example, let's augment the hardcoded MongoDB connection string with an environment variable by changing line 12 from this: + +```javascript +mongoose.connect(database.localUrl); +``` + +To this: + +```javascript +mongoose.connect(process.env.MONGO_URL || database.localUrl); +``` + +When typing `process.`, you should have noticed that VS Code displayed the available members of the Node.js `process` global API, without you needing to configure anything. + + + +This works because VS Code uses TypeScript behind the scenes (even for JavaScript!) to provide type information, which can then be used to inform the completion list as you type. VS Code is able to detect that this is a Node.js project, and as a result, automatically downloaded the TypeScript typings file for [Node.js](https://www.npmjs.com/package/@types/node) from NPM. This allows you to get completion for other Node.js globals such as `Buffer` or `setTimeout`, as well as all of the built-in modules such as `fs` and `http`. + +In addition to the built-in Node.js APIs, this auto-acquisition of typings also works for over 2,000 3rd party libraries, such as React, Underscore and Express. For example, in order to disable Mongoose from crashing the sample app if it can't connect to the configured MongoDB database instance, add the following line of code to line 13: + +```javascript +mongoose.connection.on("error", () => { console.log("DB connection error"); }); +``` + +When typing that, you'll notice that you get completion, once again, without needing to do anything. + + + +You can see which libraries support this auto-complete capability by browsing the amazing [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) project, which is the community-driven source of all TypeScript type definitions. + +## Running The App + +Now that we've explored and tweaked this app a bit, now is time to run it. To do this, simply hit `F5` to run the app. Because this is the first time we've ever tried to run it, we're asked to specify the type of "run configuration" we want to use: + + + +Select `Node.js v6.3+ (Experimental)`, which will use the new Chrome Debugging Protocol support that was recently added to Node.js. Doing this generates a new file in your project called `launch.json`, which simply tells VS Code how to launch and/or attach to your app in order to debug it. + + + +Notice that it was able to detect that the app's startup script is `server.js`, and once again, we don't need to change anything in order to make debugging just work. + +At this point, hit `F5` again to run the app. This will launch the app, along with the `Debug Console` window in VS Code, which displays stdout for our newly running app. + + + +Additionally, this console is actually attached to our newly running app, so you can type JavaScript expressions, which will be evaluated in the app, and also includes auto-completion! For example, try typing `process.env` in the console to see what I mean. + + + +If you open a browser, you can navigate to `http://localhost:8080` and see the running app. Type a message into the textbox and add/remove a few todos to get a feel for how the app works. + + + +## Debugging + +In addition to being able to run the app and interact with it via the integrated console, VS Code also provides the ability to set breakpoints directly within your code. For example, hit `CTRL+P` to bring up the file picker, type `route` and select the `route.js` file. + +Let's set a breakpoint on line 28, which represents the Express route that will be called when our app tries to add a todo. To set a breakpoint, simply click the gutter to the left of the line number within the editor: + + + +*Note: In addition to standard breakpoints, VS Code also supports conditional breakpoints, which allow you to customize when the app should suspend execution. To use them, simply right-click the gutter, select `Add Conditional Breakpoint...`, and specify either the JavaScript expression (e.g. `foo = "bar"`) or hit count that you'd like to condition the breakpoint on.* + +With that set, go back to the running app and add a todo. This immediately causes the app to suspend execution, and VS Code will pause on line 28 where we set the breakpoint: + + + +Within the paused file, we can hover over expressions to view their current value, inspect the locals/watches and call stack, and use the debug toolbar at the top to step through the execution. All the things you would expect from an IDE, but in a lightweight text editor. Hit `F5` again to continue execution of the app. + +## Full Stack Debugging + +As mentioned, this is a MEAN app, which means its front-end and back-end are both written using JavaScript. So while we're currently debugging our back-end Node/Express code, at some point, we may need to debug our front-end/Angular code. Fortunately, VS Code has a huge ecosystem of extensions, which are easy to install, including integrated Chrome debugging. + +To demonstrate this, switch to the extensions tab and type `chrome` into the search box: + + + +Select the extension named `Debugger for Chrome` and click the `Install` button. After doing this, you'll need to reload VS Code to activate the extension. It will persist your workspace across the restart so don't worry about losing any state. + +Type `CTRL+P`, enter/select `launch.json` and replace the contents of that file with the following: + +```json +{ + "version": "0.2.0", + "compounds": [ + { + "name": "Full-Stack", + "configurations": ["Node", "Chrome"] + } + ], + "configurations": [ + { + "name": "Chrome", + "type": "chrome", + "request": "launch", + "url": "http://localhost:8080", + "port": 9222, + "userDataDir": "${workspaceFolder}/.vscode/chrome", + "webRoot": "${workspaceFolder}/public" + }, + { + "name": "Node", + "type": "node2", + "request": "launch", + "program": "${workspaceFolder}/server.js", + "cwd": "${workspaceFolder}" + } + ] +} +``` + +This change does two things: + +1. Adds a new run configuration for Chrome, which will allow us to debug our front-end JavaScript code. You can hover your mouse over any of the settings that are specified to view documentation about what they do. Nice! + +2. Adds a "compound" run configuration, which will allow us to debug our front and back-end code at the same time! The compound configuration concept is really powerful, as we'll discuss later! + +To see this in action, switch to the debug tab in VS Code, and change the selected configuration to "Full-Stack" (which is what we called the compound config, you can name it anything you want), and then hit `F5` to run it. + + + +This launches the Node.js app (as can be seen in the debug console output), as well as Chrome, which is configured to navigate to the Node.js app at `http://localhost:8080`. + +Type `CTRL+P` and enter/select `todos.js`, which is the main Angular controller for the app's front-end. Set a breakpoint on line 11, which is the entry-point for a new todo being created. + +Go back to the running app, add a new todo, and you'll notice that VS Code has now suspended execution within the Angular code: + + + +Just like with the Node.js debugging, you can hover over expressions, view locals/watches, evaluate expressions in the console, etc. However, there are two cools things to consider now: + +1. The `Call Stack` pane displays two different stacks: `Node` and `Chrome`, and indicates which one is currently paused. + +2. You can step between front and back-end code! To test this, simply hit `F5`, which will run execution and hit the breakpoint we previously set in our Express route. + +With this setup, we can now efficiently debug front, back or full-stack JavaScript code directly within VS Code. Going further, the compound debugger concept isn't limited to just two target processes, and also isn't just limited to JavaScript, so if you're working on a micro-service app, that is potentially polyglot, you can use the exact same workflow we did above, once you've installed the necessary extensions (e.g. Go, Ruby, PHP). + +## Dockerizing Your App + +Speaking of microservices, let's take a look at the experience that VS Code provides for developing with Docker. Many Node.js developers are using Docker for providing portable app deployments for both development, CI and production environments. That said, we've heard lots of feedback that while the benefits of Docker are extremely high, the learning curve and cost of getting started can also be fairly high. VS Code provides an extension that tries to help simplify some of that onboarding! + +Switch back to the extensions tab, search for `docker` and select the Microsoft `Docker` extension. Install it and then reload VS Code, just like we did for the Chrome extension above. + + + +This extension includes many things, one of which is a simple command for generating a `Dockerfile` and `docker-compose.yml` file for an existing project. To see this in action, type `F1` (to bring up the command palette) and type `docker` to display all of the commands that the Docker extension provides: + + + +Select the `Docker: Add docker files to workspace` command, select `Node.js` as the app platform, and specify that the app exposes port `8080`. This generates a complete `Dockerfile` and Docker compose files that you can begin using immediately. + + + +The Docker extension also provides auto-completion for your `Dockerfiles` and `docker-compose.yml` files, which makes authoring your Docker assets a lot simpler. For example, open up the `Dockerfile` and change line 2 from: + +```docker +FROM node:latest +``` + +To: + +```docker +FROM mhart +``` + +With your cursor after the `t` in `mhart`, hit `CTRL+Space` to view all of the image repositories that `mhart` has published on DockerHub. + + + +Select `mhart/alpine-node`, which a very efficient and small Linux distro and provides everything that this app needs, without any additional bloat (Alpine Linux is great for Docker!). Smaller images are typically better since you want your app builds and deployments to be as fast as possible, which makes distribution/scaling/etc. quick. + +Now that we have our `Dockerfile`, we need to build the actual Docker image. Once again, we can use a command that the Docker extension installed, by typing `F1` and entering `dockerb` (using "fuzzy search"). Select the `Docker: Build Image` command, choose the `/Dockerfile` that we just generated/edited, and then give a tag to the image which includes your DockerHub username (e.g. `lostintangent/node`). Hit ``, which will launch the integrated terminal window and display the output of your Docker image being built. + + + +Notice that the command simply automated the process of running `docker build` for you, which is another example of a productivity enhancer that you can either choose to use, or you can just use the Docker CLI directly. Whatever works best for you! + +At this point, to make this image easily acquirable for deployments, we just need to push it to DockerHub. To do this, bring up the command palette, enter `dockerpush` and select the `Docker: Push` command. Select the image tag that you just build (e.g. `lostintangent/node`) and hit ``. This will automate calling `docker push` and will display the output in the integrated terminal. + +## Deploying Your App + +Now that we have our app Dockerized and pushed to DockerHub, we need to actually deploy it to the cloud so we can show it off to the world. For this, we'll use Azure App Service, which is Azure's PaaS offering, and recently added two new capabilities which are relevant to Node.js developers: + +1. Support for Linux-based VMs, which reduces incompatibilities for apps which are built using native Node modules, or other tools which might not support Windows and/or may behave differently. + +2. Support for Docker-based deployments, which allow you to simply specify the name of your Docker image, and allow App Service to pull, deploy and scale the image automatically. + +To get started, open up your terminal, and we'll use the new Azure CLI 2.0 to manage your Azure account and provision the necessary infrastructure to run the todo app. Once you've logged into your account from the CLI using the `az login` command (as mentioned in the pre-reqs), perform the following steps in order to provision the App Service instance and deploy the todo app container: + +1. Create a resource group, which you can think of as a "namespace" or "directory" for helping to organize Azure resources. The `-n` flag is the name of the group and can be specified as anything you want. + + ```bash + az group create -n nina-demo -l westus + ``` + + *Note: The `-l` flag indicates the location of the resource group. While in preview, the App Service on Linux support is only available in select regions, so if you aren't located in the Western US, and you want to check which other regions are available, simply run `az appservice list-locations --linux-workers-enabled` from the CLI to view your datacenter options.* + +2. Create the App Service plan, which will manage creating and scaling the underlying VMs that your app is deployed to. Once again, specify any value that you'd like for the name flag, however, make sure that the `-g` flag references the name that you gave to the resource group above. + + ```bash + az appservice plan create -n nina-demo-plan -g nina-demo --is-linux + ``` + + *Note: The `--is-linux` flag is key, since that is what indicates that you want Linux-based VMs. Without it, the CLI will provision Windows-based VMs.* + +3. Create the App Service web app, which represents the todo app that will be running within the plan and resource group we just created. You can roughly think of a web app as being synonymous with a process or container, and the plan as being the VM/container host that they're running on. + + ```bash + az appservice web create -n nina-demo-app -p nina-demo-plan -g nina-demo + ``` + +4. Configure the web app to use our Docker image, making sure to set the `-c` flag to the name of your DockerHub account/image name: + + ```bash + az appservice web config container update -n nina-demo-app -g nina-demo -c lostintangent/node + ``` + +5. Launch the app to view the container that was just deployed, which will be available at an `*.azurewebsites.net` URL: + + ```bash + az appservice web browse -n nina-demo-app -g nina-demo + ``` + + + + *Note: This may take a minute to first load your app, since App Service has to pull your Docker image from DockerHub and then start it up.* + +Yay! We just deployed our app. However, the spinning icon indicates that the app can't connect to the database, which makes sense because we were using a local instance of MongoDB during development, which obviously isn't reachable from within the Azure datacenters. Fortunately, since we updated the app to accept the connection string via an environment variable, we just need to spin up a MongoDB server and re-configure the App Service instance to reference it. + +## Using DocumentDB + +While we could setup a MongoDB server, or replica set, and manage that infrastructure ourselves, Azure provides another solution called DocumentDB. DocumentDB is a fully-managed, geo-replicable, high-performance, NoSQL database, which provides a MongoDB-compatibility layer. This means that you can point an existing MEAN app at it, without needing to change anything but the connection string! Let's take a look at how using it looks, using the Azure portal this time, instead of the CLI. + +1. Go to portal.azure.com and log into the same account you were using in the CLI. + + + +2. Press the `N` key to create a new Azure resource, and select `Databases` then `NoSQL (DocumentDB)` + + + +3. Give the instance whatever name you'd like, but configure its `NoSQL API` to use `MongoDB` and its `Resource Group` to `Use Existing` and select the same resource group that you created for the App Service instance. + + + +4. Click the `Create` button, and wait for the DB to be provisioned. + +It will take a few moments to fully create the DocumentDB instance, so wait until you see the deployment successful notification in the upper right-side of the portal. Once completed, navigate to the `All Resources` tab on the left hand navigation bar (the menu item with the green grid icon), and then select the DocumentDB resource you created: + + + +Click the `Connection String` menu item underneath the `Settings` section, and then click copy button next to the `Connection String` field in order to copy the MongoDB connection string to your clipboard. + + + +Return to the `All Resources` page within the portal, and navigate to the `App Service` instance you previously created. Click the `Application Settings` menu item underneath the `Settings` section, and add a new entry underneath the `App settings` section, whose key is `MONGO_URL` and whose value is the DocumentDB connection string that we previously copied. + + + +Hit the `Save` button, and then return to your browser and refresh it. Try adding and removing a todo item, to prove that the app now works without needing to change anything! We simply set the environment variable to our created DocumentDB instance, which is fully emulating a MongoDB database. + + + +When needed, we could switch back to the DocumentDB instance, and scale up (or down) the reserved throughput that our MongoDB instance needs, and benefit from the added traffic without needing to manage any infrastructure manually. + + + +Additionally, DocumentDB automatically indexes every single document and property for you, so you don't need to worry about profiling slow queries and/or manually fine-tuning your indexes. Just provision and scale as needed, and let DocumentDB handle the rest! + +## Clean-up + +To ensure that you don't get charged for any Azure resources you aren't using, simply run the following command from your terminal to delete all of the resources we just provisioned: + +```bash +az group delete -n nina-demo +``` + +This will take a few minutes to complete, but when done, will leave your Azure account in the same state as it was before we started. This ability to organize, deploy and delete Azure resources as a single unit is one of the primary benefits of resource groups in the first place, so in the future, if you use Azure, I would recommend grouping resources together that you'd expect to have the same lifetime. + +## Conclusion + +Hopefully this demo illustrated some of the ways that Visual Studio Code is trying to help improve the overall Node.js development experience. Between debugging that supports full-stack and microservices, a rich authoring experience that provides navigation and auto-completion without any further configuration, and a large ecosystem of extensions such as Docker, that can enhance your feedback loop for other app types and practices, we're excited to keep evolving what productivity can look like from within a lightweight editor. + +Additionally, between the Azure CLI, App Service and DocumentDB, we're trying to provide a productive and low-management cloud stack for Node.js/MEAN apps that can scale as needed, without introducing additional infrastructure complexity. + +Beyond simply providing a walkthrough of the NINA 2016 demo, we hope to use this demo to continue iterating on the overall Node.js experience in both VS Code and Azure, so we can make it simpler and more flexible. If you have any questions or feedback for how we can improve things, please don't hesitate to file an issue on this repo or send me an [e-mail](mailto:joncart@microsoft.com). Thanks! diff --git a/blogs/2017/02/08/TM-scope-inspector.gif b/blogs/2017/02/08/TM-scope-inspector.gif new file mode 100644 index 0000000000000000000000000000000000000000..06673ab95296457f75c1a19f6ed7cf4ebf854128 --- /dev/null +++ b/blogs/2017/02/08/TM-scope-inspector.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9f9ab0a17568f7a7f2e3a76548b4c45ec928c720ed721a75557a86077db0fe8d +size 390192 diff --git a/blogs/2017/02/08/TM-scopes.png b/blogs/2017/02/08/TM-scopes.png new file mode 100644 index 0000000000000000000000000000000000000000..cb96203f5b4850e27a6da6d22bf0f7b5af1d0d99 Binary files /dev/null and b/blogs/2017/02/08/TM-scopes.png differ diff --git a/blogs/2017/02/08/line-offsets.png b/blogs/2017/02/08/line-offsets.png new file mode 100644 index 0000000000000000000000000000000000000000..d6b5de2922b034e1687fffabe30694f6469cf093 Binary files /dev/null and b/blogs/2017/02/08/line-offsets.png differ diff --git a/blogs/2017/02/08/monokai-after.png b/blogs/2017/02/08/monokai-after.png new file mode 100644 index 0000000000000000000000000000000000000000..6804d992c76dc84f18590f1e0f3ad78ee0a4406f Binary files /dev/null and b/blogs/2017/02/08/monokai-after.png differ diff --git a/blogs/2017/02/08/monokai-before.png b/blogs/2017/02/08/monokai-before.png new file mode 100644 index 0000000000000000000000000000000000000000..4f9de54316d6694d0d41a41d906f76b948a81941 Binary files /dev/null and b/blogs/2017/02/08/monokai-before.png differ diff --git a/blogs/2017/02/08/monokai-tokens.png b/blogs/2017/02/08/monokai-tokens.png new file mode 100644 index 0000000000000000000000000000000000000000..5dde9efbb2bec64848c7d81d5478db8e73b16f79 Binary files /dev/null and b/blogs/2017/02/08/monokai-tokens.png differ diff --git a/blogs/2017/02/08/quiet-light-after.png b/blogs/2017/02/08/quiet-light-after.png new file mode 100644 index 0000000000000000000000000000000000000000..8d8a837fe903b79570c601ad88f46398e9adafa2 Binary files /dev/null and b/blogs/2017/02/08/quiet-light-after.png differ diff --git a/blogs/2017/02/08/quiet-light-before.png b/blogs/2017/02/08/quiet-light-before.png new file mode 100644 index 0000000000000000000000000000000000000000..2fdf867c098dd3a75e0f5a57f1d1e45c8ac13e12 Binary files /dev/null and b/blogs/2017/02/08/quiet-light-before.png differ diff --git a/blogs/2017/02/08/red-after.png b/blogs/2017/02/08/red-after.png new file mode 100644 index 0000000000000000000000000000000000000000..4ad5382bcb41375927e2009f71ba30a27e1a00c9 Binary files /dev/null and b/blogs/2017/02/08/red-after.png differ diff --git a/blogs/2017/02/08/red-before.png b/blogs/2017/02/08/red-before.png new file mode 100644 index 0000000000000000000000000000000000000000..23e39d6b1bdf492dc2f8b0d0bcdb911d48ac5f18 Binary files /dev/null and b/blogs/2017/02/08/red-before.png differ diff --git a/blogs/2017/02/08/syntax-highlighting-optimizations-social.png b/blogs/2017/02/08/syntax-highlighting-optimizations-social.png new file mode 100644 index 0000000000000000000000000000000000000000..0519d7521b71fe072438689eca231c5d2f454cc6 Binary files /dev/null and b/blogs/2017/02/08/syntax-highlighting-optimizations-social.png differ diff --git a/blogs/2017/02/08/syntax-highlighting-optimizations.md b/blogs/2017/02/08/syntax-highlighting-optimizations.md new file mode 100644 index 0000000000000000000000000000000000000000..00244956e8561f7135300f994ab588eaf7abcaae --- /dev/null +++ b/blogs/2017/02/08/syntax-highlighting-optimizations.md @@ -0,0 +1,643 @@ +--- +Order: 24 +TOCTitle: Optimizations in Syntax Highlighting +PageTitle: Optimizations in Syntax Highlighting, a Visual Studio Code Story +MetaDescription: Optimizations in tokenization and syntax highlighting in the Visual Studio Code/Monaco editor +Date: 2017-02-08 +Author: Alexandru Dima +MetaSocialImage: /assets/blogs/2017/02/08/syntax-highlighting-optimizations-social.png +--- +# Optimizations in Syntax Highlighting + +February 8, 2017 - Alexandru Dima + +Visual Studio Code version 1.9 includes a cool performance improvement that we've been working on and I wanted to tell its story. + +**TL;DR** TextMate themes will look more like their authors intended in VS Code 1.9, while being rendered faster and with less memory consumption. + +--- + +## Syntax Highlighting + +Syntax Highlighting usually consists of two phases. Tokens are assigned to source code, and then they are targeted by a theme, assigned colors, and voilà, your source code is rendered with colors. It is the one feature that turns a text editor into a code editor. + +Tokenization in VS Code (and in the [Monaco Editor](https://microsoft.github.io/monaco-editor/)) runs line-by-line, from top to bottom, in a single pass. A tokenizer can store some state at the end of a tokenized line, which will be passed back when tokenizing the next line. This is a technique used by many tokenization engines, including TextMate grammars, that allows an editor to retokenize only a small subset of the lines when the user makes edits. + +Most of the time, typing on a line results in only that line being retokenized, as the tokenizer returns the same end state and the editor can assume the following lines are not getting new tokens: + +
+Tokenization Single Line +
+ +More rarely, typing on a line results in a retokenization/repaint of the current line and some of the ones below (until an equal end state is encountered): + +
+Tokenization Multiple Lines +
+ +--- + +## How we represented tokens in the past + +The code for the editor in VS Code was written long before VS Code existed. It was shipped in the form of the [Monaco Editor](https://microsoft.github.io/monaco-editor/) in various Microsoft projects, including Internet Explorer's F12 tools. One requirement we had was to reduce memory usage. + +In the past, we wrote tokenizers by hand (there is no feasible way to interpret TextMate grammars in the browser even today, but that's another story). For the line below, we would get the following tokens from our hand-written tokenizers: + +
+Line offsets +
+ +```javascript +tokens = [ + { startIndex: 0, type: 'keyword.js' }, + { startIndex: 8, type: '' }, + { startIndex: 9, type: 'identifier.js' }, + { startIndex: 11, type: 'delimiter.paren.js' }, + { startIndex: 12, type: 'delimiter.paren.js' }, + { startIndex: 13, type: '' }, + { startIndex: 14, type: 'delimiter.curly.js' }, +] +``` + +Holding on to that tokens array takes 648 bytes in Chrome and so storing such an object is quite costly in terms of memory (each object instance must reserve space for pointing to its prototype, to its properties list, etc). Our current machines do have a lot of RAM, but storing 648 bytes for a 15 characters line is unacceptable. + +So, at the time, we came up with a binary format to store the tokens, a format that was being used up to and including [VS Code 1.8](https://github.com/Microsoft/vscode/blob/release/1.8/src/vs/editor/common/model/tokensBinaryEncoding.ts). Given that there would be duplicate token types, we collected them in a separate map (per file), doing something like the following: + +```javascript +// 0 1 2 3 4 +map = ['', 'keyword.js', 'identifier.js', 'delimiter.paren.js', 'delimiter.curly.js']; +tokens = [ + { startIndex: 0, type: 1 }, + { startIndex: 8, type: 0 }, + { startIndex: 9, type: 2 }, + { startIndex: 11, type: 3 }, + { startIndex: 12, type: 3 }, + { startIndex: 13, type: 0 }, + { startIndex: 14, type: 4 }, +] +``` + +We'd then encode the `startIndex` (32 bits) and the `type` (16 bits) in 48 bits of [the 53 mantissa bits](https://stackoverflow.com/a/2803010) a JavaScript number has. Our tokens array would finally look like this, and the map array would be reused for the entire file: + +```javascript +tokens = [ + // type startIndex + 4294967296, // 0000000000000001 00000000000000000000000000000000 + 8, // 0000000000000000 00000000000000000000000000001000 + 8589934601, // 0000000000000010 00000000000000000000000000001001 + 12884901899, // 0000000000000011 00000000000000000000000000001011 + 12884901900, // 0000000000000011 00000000000000000000000000001100 + 13, // 0000000000000000 00000000000000000000000000001101 + 17179869198, // 0000000000000100 00000000000000000000000000001110 +] +``` + +Holding on to this tokens array takes 104 bytes in Chrome. The elements themselves should take only 56 bytes (7 x 64-bit numbers), and the rest is probably explained by v8 storing other metadata with the array, or probably allocating the backing store in powers of 2. However, the memory savings are obvious and get better with more tokens per line. We were happy with this approach and we've been using this representation ever since. + +> Note: There may be more compact ways of storing the tokens, but having them in a binary-searchable linear format gives us the best trade-off in terms of memory usage and access performance. + +--- + +## Tokens <-> Theme matching + +We thought it would be a good idea to follow browser best practices, such as leaving the styling up to CSS, so when rendering the above line, we'd decode the binary tokens using the `map`, and then render it using the token types like this: + +```html + function +   + f1 + ( + ) +   + { +``` + +And we'd write our themes [in CSS](https://github.com/Microsoft/vscode/blob/1.8.0/src/vs/editor/browser/standalone/media/standalone-tokens.css) (for example the Visual Studio theme): + +```css +... +.monaco-editor.vs .token.delimiter { color: #000000; } +.monaco-editor.vs .token.keyword { color: #0000FF; } +.monaco-editor.vs .token.keyword.flow { color: #AF00DB; } +... +``` + +It turned out quite nicely, we could flip a class name somewhere and immediately get a new theme applied to the editor. + +--- + +## TextMate Grammars + +For the launch of VS Code, we had something like 10 hand-written tokenizers, mostly for web languages, which would definitely not be sufficient for a general-purpose desktop code editor. Enter [TextMate grammars](https://manual.macromates.com/en/language_grammars), a descriptive form of specifying the tokenization rules, which has been adopted in numerous editors. There was one problem though, TextMate grammars didn't work quite like our hand-written tokenizers. + +TextMate grammars, through their use of begin/end states, or while states, can push scopes that can span multiple tokens. Here's the same example under a JavaScript TextMate Grammar (ignoring whitespace for brevity): + +![TextMate Scopes](TM-scopes.png) + +--- + +## TextMate Grammars in VS Code 1.8 + +If we were to make a section through the scopes stack, each token basically gets an array of scope names, and we'd get something like the following back from the tokenizer: + +
+Line offsets +
+ +```javascript +tokens = [ + { startIndex: 0, scopes: ['source.js','meta.function.js','storage.type.function.js'] }, + { startIndex: 8, scopes: ['source.js','meta.function.js'] }, + { startIndex: 9, scopes: ['source.js','meta.function.js','meta.definition.function.js', + 'entity.name.function.js'] }, + { startIndex: 11, scopes: ['source.js','meta.function.js','meta.parameters.js', + 'punctuation.definition.parameters.js'] }, + { startIndex: 13, scopes: ['source.js','meta.function.js'] }, + { startIndex: 14, scopes: ['source.js','meta.function.js','meta.block.js', + 'punctuation.definition.block.js'] }, +] +``` + +All of the token types were strings and our code was not ready to handle string arrays, not to mention the implications on the binary encoding of tokens. We therefore proceeded to "approximate"* the array of scopes into a single string using the following strategy: + +* Ignore the least specific scope (i.e. `source.js`); it was rarely adding any value. +* Split each remaining scope on `"."`. +* De-duplicate unique pieces. +* Sort the remaining pieces with a stable sort function (not necessarily lexicographic sort). +* Join the pieces on `"."`. + +```javascript +tokens = [ + { startIndex: 0, type: 'meta.function.js.storage.type' }, + { startIndex: 9, type: 'meta.function.js' }, + { startIndex: 9, type: 'meta.function.js.definition.entity.name' }, + { startIndex: 11, type: 'meta.function.js.definition.parameters.punctuation' }, + { startIndex: 13, type: 'meta.function.js' }, + { startIndex: 14, type: 'meta.function.js.definition.punctuation.block' }, +] +``` + +> *: What we were doing was plain wrong and "approximate" is a very nice word for it :). + +These tokens would then "fit in" and would follow the same code path as the manual written tokenizers (get binary encoded), and then would render the same way too: + +```html +function +  +f1 +() +  +{ +``` + +## TextMate Themes + +TextMate Themes work with [scope selectors](https://manual.macromates.com/en/scope_selectors.html) which select tokens with certain scopes and apply theming information to them, such as color, boldness, etc. + +Given a token with the following scopes: + +```javascript +// C B A +scopes = ['source.js', 'meta.definition.function.js', 'entity.name.function.js'] +``` + +Here are some simple selectors that would match, sorted by their rank (descending): + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SelectorCBA
sourcesource.jsmeta.definition.function.jsentity.name.function.js
source.jssource.jsmeta.definition.function.jsentity.name.function.js
metasource.jsmeta.definition.function.jsentity.name.function.js
meta.definitionsource.jsmeta.definition.function.jsentity.name.function.js
meta.definition.functionsource.jsmeta.definition.function.jsentity.name.function.js
entitysource.jsmeta.definition.function.jsentity.name.function.js
entity.namesource.jsmeta.definition.function.jsentity.name.function.js
entity.name.functionsource.jsmeta.definition.function.jsentity.name.function.js
entity.name.function.jssource.jsmeta.definition.function.jsentity.name.function.js
+
+ +> Observation: `entity` wins over `meta.definition.function` because it matches a scope that is more specific (`A` over `B`, respectively). + +> Observation: `entity.name` wins over `entity` because they both match the same scope (`A`), but `entity.name` is more specific than `entity`. + +### Parent selectors + +To make things a bit more complicated, TextMate themes also support parent selectors. Here are some examples of using both simple selectors and parent selectors (again sorted by their rank descending): + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SelectorCBA
metasource.jsmeta.definition.function.jsentity.name.function.js
source metasource.jsmeta.definition.function.jsentity.name.function.js
source.js metasource.jsmeta.definition.function.jsentity.name.function.js
meta.definitionsource.jsmeta.definition.function.jsentity.name.function.js
source meta.definitionsource.jsmeta.definition.function.jsentity.name.function.js
entitysource.jsmeta.definition.function.jsentity.name.function.js
source entitysource.jsmeta.definition.function.jsentity.name.function.js
meta.definition entitysource.jsmeta.definition.function.jsentity.name.function.js
entity.namesource.jsmeta.definition.function.jsentity.name.function.js
source entity.namesource.jsmeta.definition.function.jsentity.name.function.js
+
+ +> Observation: `source entity` wins over `entity` because they both match the same scope (`A`), but `source entity` also matches a parent scope (`C`). + +> Observation: `entity.name` wins over `source entity` because they both match the same scope (`A`), but `entity.name` is more specific than `entity`. + +> Note: There is a third kind of selector, one that involves excluding scopes, which we'll not discuss here. We didn't add support for this kind and we've noticed it is rarely used in the wild. + +--- + +## TextMate Themes in VS Code 1.8 + +Here are two Monokai theme rules (as JSON here for brevity; the original is in XML): + +```json +... +// Function name +{ "scope": "entity.name.function", "fontStyle": "", "foreground":"#A6E22E" } +... +// Class name +{ "scope": "entity.name.class", "fontStyle": "underline", "foreground":"#A6E22E" } +... +``` + +In VS Code 1.8, to match our "approximated" scopes, we would generate the following dynamic CSS rules: + +```css +... +/* Function name */ +.entity.name.function { color: #A6E22E; } +... +/* Class name */ +.entity.name.class { color: #A6E22E; text-decoration: underline; } +... +``` + +We would then leave it up to CSS to match the "approximated" scopes with the "approximated" rules. But the CSS matching rules are different from the TextMate selector matching rules, especially when it comes to ranking. CSS ranking is based on the number of class names matched, while TextMate selector ranking has clear rules regarding scope specificity. + +That's why TextMate themes in VS Code would look OK, but never quite like their authors intended. Sometimes, the differences would be small, but sometimes these differences would completely change the feel of a theme. + +--- + +## Some stars lining up + +Over time, we have phased out our hand-written tokenizers (the last one, for HTML, only a couple months ago). So, in VS Code today, all the files get tokenized with TextMate grammars. For the Monaco Editor, we've migrated to using [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) (a descriptive tokenization engine similar at heart with TextMate grammars, but a bit more expressive and that can run in a browser) for most of the supported languages, and we've added a wrapper for manual tokenizers. All in all, that means supporting a new tokenization format would require changing 3 tokens providers (TextMate, Monarch and the manual wrapper) and not more than 10. + +A few months ago we reviewed all the code we have in the VS Code core that reads token types and we noticed that those consumers only cared about strings, regular expressions or comments. For example, the bracket matching logic ignores tokens that contain the scope `"string"`, `"comment"` or `"regex"`. + +Recently we've gotten the OK from our internal partners (other teams inside Microsoft consuming the Monaco Editor), that they no longer need support for IE9 and IE10 in the Monaco Editor. + +Probably most important, the number one most voted feature for the editor is [minimap support](https://github.com/Microsoft/vscode/issues/4865). To render a minimap in a reasonable amount of time, we cannot use DOM nodes and CSS matching. We will probably use a canvas, and we're going to need to know the color of each token in JavaScript, so we can paint those tiny letters with the right colors. + +Perhaps the biggest breakthrough we've had is that we **don't need to store tokens, nor their scopes**, since tokens only produce effects in terms of a theme matching them or in terms of bracket matching skipping strings. + +## Finally, what's new in VS Code 1.9 + +### Representing a TextMate theme + +Here's how a very simple theme might look like: + +```json +theme = [ + { "foreground": "#F8F8F2" }, + { "scope": "var", "foreground": "#F8F8F2" }, + { "scope": "var.identifier", "foreground": "#00FF00", "fontStyle": "bold" }, + { "scope": "meta var.identifier", "foreground": "#0000FF" }, + { "scope": "constant", "foreground": "#100000", "fontStyle": "italic" }, + { "scope": "constant.numeric", "foreground": "#200000" }, + { "scope": "constant.numeric.hex", "fontStyle": "bold" }, + { "scope": "constant.numeric.oct", "fontStyle": "underline" }, + { "scope": "constant.numeric.dec", "foreground": "#300000" }, +]; +``` + +When loading it, we will generate an id for each unique color that shows up in the theme and store it into a color map (similar as we did for token types above): + + +```json +// 1 2 3 4 5 6 +colorMap = ["reserved", "#F8F8F2", "#00FF00", "#0000FF", "#100000", "#200000", "#300000"] +theme = [ + { "foreground": 1 }, + { "scope": "var", "foreground": 1, }, + { "scope": "var.identifier", "foreground": 2, "fontStyle": "bold" }, + { "scope": "meta var.identifier", "foreground": 3 }, + { "scope": "constant", "foreground": 4, "fontStyle": "italic" }, + { "scope": "constant.numeric", "foreground": 5 }, + { "scope": "constant.numeric.hex", "fontStyle": "bold" }, + { "scope": "constant.numeric.oct", "fontStyle": "underline" }, + { "scope": "constant.numeric.dec", "foreground": 6 }, +]; +``` + +We will then generate a [Trie](https://en.wikipedia.org/wiki/Trie) data structure out of the theme rules, where each node holds on to the resolved theme options: + +
+Theme Trie +
+ +> Observation: The nodes for `constant.numeric.hex` and `constant.numeric.oct` contain the instruction to change foreground to `5`, as they *inherit* this instruction from `constant.numeric`. + +> Observation: The node for `var.identifier` holds on to the extra parent rule `meta var.identifier` and will answer queries accordingly. + +When we want to find out how a scope should be themed, we can query this trie. + +For example: + +| Query | Results | +|-----------|---------| +| constant | set foreground to 4, fontStyle to italic | +| constant.numeric | set foreground to 5, fontStyle to italic | +| constant.numeric.hex | set foreground to 5, fontStyle to bold | +| var | set foreground to 1 | +| var.baz | set foreground to 1 (matches var) | +| baz | do nothing (no match) | +| var.identifier | if there is a parent scope meta, then set foreground to 3, fontStyle to bold,
otherwise, set foreground to 2, fontStyle to bold | + + +### Changes to tokenization + +All the TextMate tokenization code used in VS Code lives in a separate project, [vscode-textmate](https://github.com/Microsoft/vscode-textmate), which can be used independently of VS Code. We've changed the way we represent the scope stack in `vscode-textmate` to be [an immutable linked list](https://github.com/Microsoft/vscode-textmate/blob/master/src/grammar.ts#L946) that also stores the fully resolved `metadata`. + +When pushing a new scope onto the scope stack, we will look up the new scope in the theme trie. We can then compute immediately the fully resolved desired foreground or font style for a scope list, based on what we inherit from the scope stack and on what the theme trie returns. + +Some examples: + +| Scope Stack | Metadata | +|---|---| +| ["source.js"] | foreground is 1, font style is regular (the default rule without a scope selector) | +| ["source.js","constant"] | foreground is 4, fontStyle is italic | +| ["source.js","constant","baz"] | foreground is 4, fontStyle is italic | +| ["source.js","var.identifier"] | foreground is 2, fontStyle is bold | +| ["source.js","meta","var.identifier"] | foreground is 3, fontStyle is bold | + +When popping from the scope stack, there is no need to compute anything, since we can just use the metadata stored with the previous scope list element. + +Here's the TypeScript class that represents an element in the scope list: + +```typescript +export class ScopeListElement { + public readonly parent: ScopeListElement; + public readonly scope: string; + public readonly metadata: number; + ... +} +``` + +We store 32 bits of metadata: + +``` +/** + * - ------------------------------------------- + * 3322 2222 2222 1111 1111 1100 0000 0000 + * 1098 7654 3210 9876 5432 1098 7654 3210 + * - ------------------------------------------- + * xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx + * bbbb bbbb bfff ffff ffFF FTTT LLLL LLLL + * - ------------------------------------------- + * - L = LanguageId (8 bits) + * - T = StandardTokenType (3 bits) + * - F = FontStyle (3 bits) + * - f = foreground color (9 bits) + * - b = background color (9 bits) + */ +``` + +Finally, instead of emitting tokens as objects from the tokenization engine: + +```javascript +// These are generated using the Monokai theme. +tokens_before = [ + { startIndex: 0, scopes: ['source.js','meta.function.js','storage.type.function.js'] }, + { startIndex: 8, scopes: ['source.js','meta.function.js'] }, + { startIndex: 9, scopes: ['source.js','meta.function.js','meta.definition.function.js', + 'entity.name.function.js'] }, + { startIndex: 11, scopes: ['source.js','meta.function.js','meta.parameters.js', + 'punctuation.definition.parameters.js'] }, + { startIndex: 13, scopes: ['source.js','meta.function.js'] }, + { startIndex: 14, scopes: ['source.js','meta.function.js','meta.block.js', + 'punctuation.definition.block.js'] }, +] + +// Every even index is the token start index, every odd index is the token metadata. +// We get fewer tokens because tokens with the same metadata get collapsed +tokens_now = [ + // bbbbbbbbb fffffffff FFF TTT LLLLLLLL + 0, 16926743, // 000000010 000001001 001 000 00010111 + 8, 16793623, // 000000010 000000001 000 000 00010111 + 9, 16859159, // 000000010 000000101 000 000 00010111 + 11, 16793623 // 000000010 000000001 000 000 00010111 +] +``` + +And they get rendered with: + +```html +function +  +f1 +() { +``` + +![TextMate Scopes](monokai-tokens.png) + +The tokens are returned as an [Uint32Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint32Array) straight from the tokenizer. We hold on to the backing [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) and for the example above that takes 96 bytes in Chrome. The elements themselves should take only 32 bytes (8 x 32-bit numbers), but again we're probably observing some v8 metadata overhead. + +### Some numbers + +To get the following measurements, I've picked three files with different characteristics and different grammars: + +| File name | File size | Lines | Language | Observation | +|---|---|---|---|---| +| checker.ts | 1.18 MB | 22,253 | TypeScript | Actual source file used in TypeScript compiler | +| bootstrap.min.css | 118.36 KB | 12 | CSS | Minified CSS file | +| sqlite3.c | 6.73 MB | 200,904 | C | Concatenated distribution file of SQLite + +I've run the tests on a somewhat powerful desktop machine on Windows (which uses Electron 32 bit). + +I had to make some changes to the source code in order to compare apples with apples, such as ensuring the exact same grammars are used in both VS Code versions, turning off rich language features in both versions, or lifting the 100 stack depth limitation in VS Code 1.8 which no longer exists in VS Code 1.9, etc. I also had to split bootstrap.min.css into multiple lines to get each line under 20k chars. + +### Tokenization times + +Tokenization runs in a yielding fashion on the UI thread, so I had to add some code to force it to run synchronously in order to measure the following times (median of 10 runs presented): + +| File name | File size | VS Code 1.8 | VS Code 1.9 | Speed-up | +|---|---|---|---|---| +| checker.ts | 1.18 MB | 4606.80 ms | 3939.00 ms | 14.50% | +| bootstrap.min.css | 118.36 KB | 776.76 ms | 416.28 ms | 46.41% | +| sqlite3.c | 6.73 MB | 16010.42 ms | 10964.42 ms | 31.52% | + +
+Tokenization times +
+ +> Although tokenization now also does theme matching, the time savings can be explained by doing a single pass over each line. Whereas before, there would be a tokenization pass, a secondary pass to "approximate" the scopes to a string, and a third pass to binary encode the tokens, now the tokens are generated straight in a binary encoded fashion from the TextMate tokenization engine. The amount of generated objects that need to be garbage collected has been also reduced substantially. + +### Memory usage + +Folding is consuming a lot of memory, especially for large files (that's an optimization for another time), so I've collected the following Heap Snapshot numbers with folding turned off. This shows the memory held by the Model, without accounting for the original file string: + +| File name | File size | VS Code 1.8 | VS Code 1.9 | Memory savings | +|---|---|---|---|---| +| checker.ts | 1.18 MB | 3.37 MB | 2.61 MB | 22.60% | +| bootstrap.min.css | 118.36 KB | 267.00 KB | 201.33 KB | 24.60% | +| sqlite3.c | 6.73 MB | 27.49 MB | 21.22 MB | 22.83% | + +
+Memory usage +
+ +> The reduced memory usage can be explained by no longer holding on to a tokens map, the collapse of consecutive tokens with the same metadata, and the usage of `ArrayBuffer` as the backing store. We could further improve here by always collapsing whitespace-only tokens into the previous token, as it does not matter what color whitespace gets rendered (whitespace is invisible). + +### New TextMate Scope Inspector Widget + +We've added a new widget to help with authoring and debugging themes or grammars: You can run it with **Developer: Inspect TM Scopes** in the **Command Palette** (`kb(workbench.action.showCommands)`). + +![TextMate scope inspector](TM-scope-inspector.gif) + +### Validating the change + +Making changes in this component of the editor presented some serious risk as any bug in our approach (in the new trie creation code, in the new binary encoding format, etc) could potentially result in huge user-visible differences. + +In VS Code, we have an integration suite that asserts colors for all the programming languages we ship across the five themes we author (Light, Light+, Dark, Dark+, High Contrast). These tests are very helpful both when making changes to one of our themes and also when updating a certain grammar. Each of the 73 integration tests consists of a fixture file (for example [test.c](https://github.com/Microsoft/vscode/blob/release/1.9/extensions/cpp/test/colorize-fixtures/test.c)) and the expected colors for the five themes ([test_c.json](https://github.com/Microsoft/vscode/blob/release/1.9/extensions/cpp/test/colorize-results/test_c.json)), and they run on each commit on our [CI build](https://travis-ci.org/Microsoft/vscode/jobs/198766250#L3184). + +To validate the tokenization change, we've collected colorization results from these tests, across all the 14 themes we ship with (not just the five themes we author) using the old CSS based approach. Then, after each change, we ran the same tests using the new trie-based logic and, using a custom-built visual diff (and patch) tool, we would look into each and every color difference and figure out the root cause of the color change. We caught at least 2 bugs using this technique and we were able to change our five themes to get minimal color changes across VS Code versions: + +![Tokenization validation](tokenization-validation.png) + +### Before and After + +Below are various color themes as they appeared in VS Code 1.8 and now in VS Code 1.9: + +Monokai Theme + +![Monokai before](monokai-before.png) + +![Monokai after](monokai-after.png) + +Quiet Light Theme + +![Quiet Light before](quiet-light-before.png) + +![Quiet Light after](quiet-light-after.png) + +Red Theme + +![Red before](red-before.png) + +![Red after](red-after.png) + +## In conclusion + +I hope you will appreciate the extra CPU time and RAM you get from upgrading to VS Code 1.9 and that we can continue to empower you to code in an efficient and pleasant way. + +Happy coding! + +[Alexandru Dima](https://github.com/alexandrudima/), VS Code Team Member +[@alexdima123](https://twitter.com/alexdima123) diff --git a/blogs/2017/02/08/tokenization-1.gif b/blogs/2017/02/08/tokenization-1.gif new file mode 100644 index 0000000000000000000000000000000000000000..d68bb1503d1c658d0201f5d866e911f554b4b2c6 Binary files /dev/null and b/blogs/2017/02/08/tokenization-1.gif differ diff --git a/blogs/2017/02/08/tokenization-2.gif b/blogs/2017/02/08/tokenization-2.gif new file mode 100644 index 0000000000000000000000000000000000000000..8e7911cd9a471c23dd651792602021331abbcf70 --- /dev/null +++ b/blogs/2017/02/08/tokenization-2.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0081d5826882148978ae8891556d1a767940ff969f7853ed4c067d78f69e3e19 +size 533524 diff --git a/blogs/2017/02/08/tokenization-memory.png b/blogs/2017/02/08/tokenization-memory.png new file mode 100644 index 0000000000000000000000000000000000000000..d4023964105fc7fd7fe2a0c679a275eda566a44d Binary files /dev/null and b/blogs/2017/02/08/tokenization-memory.png differ diff --git a/blogs/2017/02/08/tokenization-times.png b/blogs/2017/02/08/tokenization-times.png new file mode 100644 index 0000000000000000000000000000000000000000..a61b9994d76f7f753b515399989fe22067c86b3c Binary files /dev/null and b/blogs/2017/02/08/tokenization-times.png differ diff --git a/blogs/2017/02/08/tokenization-validation.png b/blogs/2017/02/08/tokenization-validation.png new file mode 100644 index 0000000000000000000000000000000000000000..71e6999ba033a455ecfad55a72e9569b2f5f208e Binary files /dev/null and b/blogs/2017/02/08/tokenization-validation.png differ diff --git a/blogs/2017/02/08/trie.png b/blogs/2017/02/08/trie.png new file mode 100644 index 0000000000000000000000000000000000000000..9bf502cf04acf3294806ee3fefe50f51f9c1ca4f Binary files /dev/null and b/blogs/2017/02/08/trie.png differ diff --git a/blogs/2017/02/12/appinsights.gif b/blogs/2017/02/12/appinsights.gif new file mode 100644 index 0000000000000000000000000000000000000000..f40798baa867989d9412103fcae99de97e7ce59f Binary files /dev/null and b/blogs/2017/02/12/appinsights.gif differ diff --git a/blogs/2017/02/12/code-lens-roundup.md b/blogs/2017/02/12/code-lens-roundup.md new file mode 100644 index 0000000000000000000000000000000000000000..d699f2e56ee5e821220aa9d3cc7f71931f2be532 --- /dev/null +++ b/blogs/2017/02/12/code-lens-roundup.md @@ -0,0 +1,109 @@ +--- +Order: 25 +TOCTitle: Extensions using CodeLens +PageTitle: Visual Studio Code Extensions using CodeLens +MetaDescription: Visual Studio Code Extensions using CodeLens +Date: 2017-02-12 +ShortDescription: Visual Studio Code Extensions using CodeLens +Author: Wade Anderson +--- +# Extensions using CodeLens + +February 12, 2017 Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +CodeLens is a popular feature in Visual Studio Code. The essence of the feature is "actionable contextual information interspersed" in your source code. That's quite a mouthful. Let me break it down for you. + +CodeLens are links in your code: + +- **Actionable** - You can click on the link and something happens. +- **Contextual** - The links are close to the code they are representing. +- **Interspersed** - The links located throughout your source code. + +![animation showing CodeLens](code_lens.gif) + +VS Code comes with CodeLens for TypeScript. You can enable it in User Settings with `"typescript.referencesCodeLens.enabled": true`. + +![CodeLens in TypeScript](typescript_code_lens.png) + +You can create your own extension with the CodeLens feature. Get started by checking out the [documentation](/docs/extensionAPI/language-support.md#codelens-show-actionable-context-information-within-source-code). Additionally, you can find popular extensions in the Marketplace that use CodeLens. This blog post lists some of my favorite. + +> **Tip:** You can install all of these extensions at once by installing the [CodeLens Roundup](https://marketplace.visualstudio.com/items?itemName=waderyan.code-lens-roundup) Extension Pack. How do you bundle extensions together? Check out [Extension Packs](/docs/extensionAPI/extension-manifest.md#extension-packs). + +## Git Lens + +Marketplace - [Git Lens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) + +Author - [eamodio](https://marketplace.visualstudio.com/search?term=publisher%3A%22eamodio%22&target=VSCode) + +This feature-rich extension will meet all your Git needs. eamodio uses the CodeLens UI to show you the most recent commit, number of authors, inline blame annotations, and exposes the Peek window for a full history view. See the extension's [README](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) for the full list of features. With 14 five stars, this is a highly rated, excellent extension. + +![animation showing gitlens](preview_gitlens.gif) + +## Azure Application Insights + +Marketplace - [Azure Application Insights](https://marketplace.visualstudio.com/items?itemName=VisualStudioOnlineApplicationInsights.application-insights) + +Author - [Microsoft](https://marketplace.visualstudio.com/search?term=publisher%3A%22Microsoft%22&target=VSCode) + +As you can imagine, this is a popular one on the VS Code team. Use this extension to see information on your production services right in VS Code! + +![app insights](appinsights.gif) + +## CodeMetrics + +Marketplace - [CodeMetrics](https://marketplace.visualstudio.com/items?itemName=kisstkondoros.vscode-codemetrics) + +Author - [Kiss Tamás](https://marketplace.visualstudio.com/search?term=publisher%3A%22Kiss%20Tam%C3%A1s%22&target=VSCode) + +Imagine you have this colleague who likes to write complex functions. They thinks it's cool and are less concerned with maintainability. Use this extension to show them the complexity of their functions and also to check metrics on the source code you are writing. + +![code metrics](codemetrics.png) + +As an added bonus, you can customize the descriptions. Here is the configuration we like to use on our team: + +``` +"codemetrics.basics.ComplexityLevelExtremeDescription": "😱", +"codemetrics.basics.ComplexityLevelHighDescription": "😳", +"codemetrics.basics.ComplexityLevelLowDescription": "🤓", +"codemetrics.basics.ComplexityLevelNormalDescription": "🤔", +"codemetrics.basics.ComplexityTemplate": "Complexity is {0} {1}" +``` + +As you can see, we like emojis. + +## Regex Previewer + +Marketplace - [Regex Previewer](https://marketplace.visualstudio.com/items?itemName=chrmarti.regex) + +Author - [Christof Marti](https://marketplace.visualstudio.com/search?term=publisher%3A%22Christof%20Marti%22&target=VSCode) + +Do you write a lot of regular expressions? This is an excellent extension to quickly test your regex. + +![regex](regex.gif) + +## Version Lens + +Marketplace - [Version Lens](https://marketplace.visualstudio.com/items?itemName=pflannery.vscode-versionlens) + +Author - [pflannery](https://marketplace.visualstudio.com/search?term=publisher%3A%22pflannery%22&target=VSCode) + +With support for many package management systems, including npm, bower, dotnet, and jspm, this extension is very useful. Install the extension and see what packages are out of date. With a quick click of the mouse, you can upgrade the version. + +![version lens demo](versionlens.png) + +## Pro Tip - Preview your Extension + +Marketplace - [Extension Manifest Editor](https://marketplace.visualstudio.com/items?itemName=ms-devlabs.extension-manifest-editor) + +Author - [Microsoft DevLabs](https://marketplace.visualstudio.com/search?term=publisher%3A%22Microsoft%20DevLabs%22&target=VSCode) + +Sometimes when I'm making an extension, I think it would be great to see how the extension will look in the Marketplace before publishing. The Extension Manifest Editor allows you to preview your extension's Marketplace presentation within VS Code. + +![manifest preview](manifest_preview.gif) + +## Want to see your extension featured? + +Have other extensions you like or want to see your extension in the next roundup? Ping me on Twitter! + +Wade Anderson, VS Code Team Member  +[@waderyan_](https://twitter.com/waderyan_) \ No newline at end of file diff --git a/blogs/2017/02/12/code_lens.gif b/blogs/2017/02/12/code_lens.gif new file mode 100644 index 0000000000000000000000000000000000000000..f8fa2e94bc35ec29b84299f52586ebce4028ab95 --- /dev/null +++ b/blogs/2017/02/12/code_lens.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1f7c679c7db4748a4308e8fe66aef9051cd2937035de6dc14667931015bc5dc2 +size 1188639 diff --git a/blogs/2017/02/12/codemetrics.png b/blogs/2017/02/12/codemetrics.png new file mode 100644 index 0000000000000000000000000000000000000000..b418540d59d1fa9e42a5a2dc8ba7e80af06e7767 Binary files /dev/null and b/blogs/2017/02/12/codemetrics.png differ diff --git a/blogs/2017/02/12/manifest_preview.gif b/blogs/2017/02/12/manifest_preview.gif new file mode 100644 index 0000000000000000000000000000000000000000..f631db9b3a117e93dce94978bf6d776dc36d69ed --- /dev/null +++ b/blogs/2017/02/12/manifest_preview.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cc0c9a6b104a3a0a880d897abf90ccfe3ef951dbb6d77b5f5fb5864a0069cb53 +size 736411 diff --git a/blogs/2017/02/12/preview_gitlens.gif b/blogs/2017/02/12/preview_gitlens.gif new file mode 100644 index 0000000000000000000000000000000000000000..c6e8ff200522c24eeffc39625d2854163b3dd5ae --- /dev/null +++ b/blogs/2017/02/12/preview_gitlens.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:278d654662341e1704c671d90eb4cdc6c8e09b1259e16fbc3181bda5cd1c8113 +size 1192144 diff --git a/blogs/2017/02/12/regex.gif b/blogs/2017/02/12/regex.gif new file mode 100644 index 0000000000000000000000000000000000000000..7c25f952ac42dbd4d6164aaca1747d9b97c7c840 Binary files /dev/null and b/blogs/2017/02/12/regex.gif differ diff --git a/blogs/2017/02/12/typelens.png b/blogs/2017/02/12/typelens.png new file mode 100644 index 0000000000000000000000000000000000000000..b675044a11fd57665c8616ae1e2a0ed5e9e4942b Binary files /dev/null and b/blogs/2017/02/12/typelens.png differ diff --git a/blogs/2017/02/12/typescript_code_lens.png b/blogs/2017/02/12/typescript_code_lens.png new file mode 100644 index 0000000000000000000000000000000000000000..e9811793de79c3ace8270ef0c64cb127e73d9153 Binary files /dev/null and b/blogs/2017/02/12/typescript_code_lens.png differ diff --git a/blogs/2017/02/12/versionlens.png b/blogs/2017/02/12/versionlens.png new file mode 100644 index 0000000000000000000000000000000000000000..8e645efb34bd693cb3822c80e93a33795a82d99e Binary files /dev/null and b/blogs/2017/02/12/versionlens.png differ diff --git a/blogs/2017/03/07/create_extension_pack.png b/blogs/2017/03/07/create_extension_pack.png new file mode 100644 index 0000000000000000000000000000000000000000..67a97910dec541d7899c20f6d147d2ee074cc80e Binary files /dev/null and b/blogs/2017/03/07/create_extension_pack.png differ diff --git a/blogs/2017/03/07/extension-pack-roundup.md b/blogs/2017/03/07/extension-pack-roundup.md new file mode 100644 index 0000000000000000000000000000000000000000..8e76efc11b80f90fd9f7ae615dca35ac8dfb5997 --- /dev/null +++ b/blogs/2017/03/07/extension-pack-roundup.md @@ -0,0 +1,82 @@ +--- +Order: 26 +TOCTitle: Extension Packs +PageTitle: Visual Studio Code Extension Packs +MetaDescription: Learn how to create and use Extension Packs in Visual Studio Code. +Date: 2017-03-07 +ShortDescription: Learn how to create and use Extension Packs in Visual Studio Code. +Author: Wade Anderson +--- +# Extension Packs + +March 07, 2017 Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +If you have followed our blog for the last year, you'll notice I write an Extension Roundup blog once a month. I like to write these blogs to let you know about the cool extensions being created in the community and to inspire you to create your own. I often put a theme around the Roundup blog: something like JavaScript extensions or CodeLens extensions (last month). + +Creating a theme for this blog is a natural fit for a relatively new part of the extension API, Extension Packs. Last month I created my [first Extension Pack](https://marketplace.visualstudio.com/items?itemName=waderyan.code-lens-roundup) to bring together all of my favorite CodeLens extensions. In this month's Roundup, I want to teach you how to make your own pack and give you some examples of why you would want to. + +> **Tip** Refer to the [Extension Pack documentation](https://code.visualstudio.com/docs/extensionAPI/extension-manifest#_extension-packs) for more details. + +## How do I make an Extension Pack? + +It is very easy to make your own Extension Pack. Follow the instructions on installing the Yeoman VS Code [extension generator](https://code.visualstudio.com/docs/extensions/yocode). + +Once the Yeoman generator is installed, run the following command: + +```zsh +yo code +``` + +Choose `New Extension Pack` as shown in the image below. + +![new extension pack](create_extension_pack.png) + +Fill out the options as given by Yeoman. One of the options is to create an Extension Pack based on the extensions you currently have installed. This will fill out much of the Extension Pack's details for you! + +To include an extension, your extension manifest file (`package.json`) needs the following attribute: + +```js +"extensionDependencies": [ + "publisherid.extensionName" + ] +``` + +> **Tip** You can see the publisherid.extensionName at the end of the URL of an extension on the Marketplace. + +For my CodeLens Roundup, this is what my extension manifest file looked like: + +```json +"extensionDependencies": [ + "eamodio.gitlens", + "VisualStudioOnlineApplicationInsights.application-insights", + "kisstkondoros.vscode-codemetrics", + "chrmarti.regex", + "pflannery.vscode-versionlens" +] +``` + +## Why would I want to create an Extension Pack? + +There are many reasons to create an Extension Pack: + +- Want to create a list of your favorite extensions to share with your friends? Use an Extension Pack. +- Want to bundle your Python extensions, so you can easily disable and enable when you are working on a Python project? Use an Extension Pack. +- Want to create a curated list of extensions for a blog post on VS Code's website? Use an Extension Pack. + +## Recommended Extension Packs + +You can find the Extension Packs that others have created by querying using the Extension Pack category: click [here](https://marketplace.visualstudio.com/search?target=vscode&category=Extension%20Packs&sortBy=Downloads) for the Marketplace or type `category:"Extension Packs"` into the Extension View search bar in VS Code. + +Some of my favorite extensions are: + +* **[Azure Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-azureextensionpack)** by [Microsoft](https://marketplace.visualstudio.com/search?term=publisher%3A%22Microsoft%22&target=VSCode&sortBy=Relevance). If you use Azure resources, this is a must. We created this pack to group the various Azure extensions into one installation. +* **[React Native iOS Pack](https://marketplace.visualstudio.com/items?itemName=bierner.react-native-ios-pack)** by [Matt Bierner](https://marketplace.visualstudio.com/search?term=publisher%3A%22Matt%20Bierner%22&target=VSCode). Matt has put together good tools for working with React Native, Objective-C, and Swift. +* **[PHP Extension Pack](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-pack)** by [Felix Becker](https://marketplace.visualstudio.com/search?term=publisher%3A%22Felix%20Becker%22&target=VSCode). Felix has created a couple popular PHP extensions for VS Code. This is a simple pack he made to bundle them together. +* **[Node.js Extension Pack](https://marketplace.visualstudio.com/items?itemName=waderyan.nodejs-extension-pack)** by [waderyan](https://marketplace.visualstudio.com/search?term=publisher%3A%22Wade%20Anderson%22&target=VSCode). Disclaimer: Shameless self-promotion 😊. I created this extension to pull together my favorite Node.js extensions from previous blog posts. + +## Want to see your extension featured? + +Have other extensions you like or want to see your extension in the next Roundup? Ping me on [Twitter](https://twitter.com/waderyan_)! + +Wade Anderson, VS Code Team Member  +[@waderyan_](https://twitter.com/waderyan_) \ No newline at end of file diff --git a/blogs/2017/04/10/close_html_xml_tag.gif b/blogs/2017/04/10/close_html_xml_tag.gif new file mode 100644 index 0000000000000000000000000000000000000000..8d9bc368dc3fa1e45acbc40d4be45dd4da1a6172 --- /dev/null +++ b/blogs/2017/04/10/close_html_xml_tag.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5a4e8462a3f92deb642865ab6bd3c1a2c1fc1165d6eb2259de1612cd6c7fac97 +size 191143 diff --git a/blogs/2017/04/10/expand_selection.gif b/blogs/2017/04/10/expand_selection.gif new file mode 100644 index 0000000000000000000000000000000000000000..0396e645c05c7413b87869f382051e6f8025194a Binary files /dev/null and b/blogs/2017/04/10/expand_selection.gif differ diff --git a/blogs/2017/04/10/sublime-text-roundup.md b/blogs/2017/04/10/sublime-text-roundup.md new file mode 100644 index 0000000000000000000000000000000000000000..536d11c1affd3bcd35993783a1640c43936fc417 --- /dev/null +++ b/blogs/2017/04/10/sublime-text-roundup.md @@ -0,0 +1,99 @@ +--- +Order: 27 +TOCTitle: Sublime Text Extension Roundup +PageTitle: Sublime Text Extension Roundup +MetaDescription: Learn about VS Code extensions to add features that are missing from Sublime Text. +Date: 2017-04-10 +ShortDescription: Learn about VS Code extensions to add features that are missing from Sublime Text. +Author: Wade Anderson +--- +# Sublime Text Extension Roundup + +April 10, 2017 Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +I'm a big fan of Sublime Text. It was my [go to editor](https://www.youtube.com/watch?v=OnkYnm-WiVo&t=15s) for my first few years of programming. Naturally, I now like VS Code more, but sometimes I miss things from Sublime Text. + +We wrote an [extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.sublime-keybindings) to help alleviate some of the pain I felt (for example, keyboard muscle memory). There is still more work to do (see this [GitHub issue](https://github.com/Microsoft/vscode/issues/3776)), but the gaps are closing fast. You can find other extensions to cover almost all of the features you are missing. + +In this blog, I'll present some existing VS Code features and suggested extensions to help you if you are coming from Sublime Text. + +>**Tip:** To install all of the extensions mentioned in this blog post, check out this [extension pack](https://marketplace.visualstudio.com/items?itemName=waderyan.sublime-text-pack). + +## VS Code features + +VS Code has several features you can enable to more closely match the coding experience on Sublime Text. + +## Minimap + +VS Code has an excellent minimap, but it requires a setting change. Use the following setting to turn on the minimap: + +```json +"editor.minimap.enabled": true +``` + +## Format on Paste + +Format on paste is a fantastic feature when moving source code around. Use this setting to enable format on paste: + +```json +"editor.formatOnPaste": true +``` + +## Suggestion Ordering + +Sublime Text and VS Code order snippets differently in their code completion widgets. To make VS Code work more like Sublime Text, use this setting to put snippets at the top: + +```json +"editor.snippetSuggestions": "top" +``` + +## Extensions + +To ease moving from Sublime Text, I recommend using the following extensions: + +## Sublime Text Keymap + +Marketplace - [Sublime Text Keymap](https://marketplace.visualstudio.com/items?itemName=ms-vscode.sublime-keybindings) + +Author - [Microsoft](https://marketplace.visualstudio.com/search?term=publisher%3A%22Microsoft%22&target=VSCode) + +You have memorized the keyboard shortcuts and you won't need to change your muscle memory to move to VS Code. This extension ports the most popular keyboard shortcuts from Sublime Text to VS Code. + +![sublime text keymap](sublime_text_keymap.png) + +> **Tip:** There are some conflicts with VS Code and Sublime Text keyboard shortcuts. Currently the extension chooses Sublime Text's shortcuts over VS Code's. This means that some VS Code keyboard shortcuts don't work the same after installing the extension (for example, `kbstyle(F5)` to debug). You can easily modify any shortcut yourself with **Preferences** > **Keyboard Shortcuts**. + +## Expand Selection To Scope + +Marketplace - [Expand Selection To Scope](https://marketplace.visualstudio.com/items?itemName=vittorioromeo.expand-selection-to-scope) + +Author - [Vittorio Romeo](https://marketplace.visualstudio.com/search?term=publisher%3A%22Vittorio%20Romeo%22&target=VSCode) + +VS Code has existing support for expanding text selection, but this extension hits a nice sweet spot. Expand your selection to the scope incrementally, including for multiple cursors. + +![expand selection](expand_selection.gif) + +## Close HTML / XML Tag + +Marketplace - [Close HTML / XML tag](https://marketplace.visualstudio.com/items?itemName=Compulim.compulim-vscode-closetag) + +Author - [Compulim](https://marketplace.visualstudio.com/search?term=publisher%3A%22Compulim%22&target=VSCode) + +Adds a keyboard shortcut to add the closing tag for XML and HTML. + +![close html xml tag](close_html_xml_tag.gif) + +## Sublime Commands + +Marketplace - [Sublime Commands](https://marketplace.visualstudio.com/items?itemName=Zarel.sublime-commands) + +Author - [Zarel](https://marketplace.visualstudio.com/search?term=publisher%3A%22Zarel%22&target=VSCode) + +Ports the **Transpose**, **Expand Selection to Line**, and **Split into Lines** commands to VS Code. + +## Want to see your extension featured? + +Have other extensions you like or want to see your extension in the next Roundup? Ping me on [Twitter](https://twitter.com/waderyan_)! + +Wade Anderson, VS Code Team Member +[@waderyan_](https://twitter.com/waderyan_) \ No newline at end of file diff --git a/blogs/2017/04/10/sublime_text_keymap.png b/blogs/2017/04/10/sublime_text_keymap.png new file mode 100644 index 0000000000000000000000000000000000000000..14005c6c08cce081e3ee4fd1e6b05bcc8af813bf Binary files /dev/null and b/blogs/2017/04/10/sublime_text_keymap.png differ diff --git a/blogs/2017/05/10/build-2017-demo.md b/blogs/2017/05/10/build-2017-demo.md new file mode 100644 index 0000000000000000000000000000000000000000..f27e61b348a4d618b74c8d4d4de01db228954a79 --- /dev/null +++ b/blogs/2017/05/10/build-2017-demo.md @@ -0,0 +1,82 @@ +--- +Order: 28 +TOCTitle: Build 2017 Demo +PageTitle: Build 2017 Demo +MetaDescription: Build 2017 Demo Visual Studio Code - Conquering the Cloud with an editor and a CLI +Date: 2017-05-10 +ShortDescription: Build 2017 Demo Visual Studio Code - Conquering the Cloud with an editor and a CLI +Author: Chris Dias +--- +# Build 2017 Demo + +May 10, 2017 Chris Dias, [@chrisdias](https://twitter.com/chrisdias) + +## Watch the video + +[Visual Studio Code: Conquering the Cloud with an Editor and a CLI](https://channel9.msdn.com/Events/Build/2017/B8094) + +Below are links to the samples, tools, and extensions demonstrated in the Build 2017 VS Code talk. + +## Samples + +* [StickerApp](https://github.com/glimpse/stickerapp) is a full featured version of the app used in the demo. + +## Tools + +* [NPM (Node Package Manager) Support](https://marketplace.visualstudio.com/items?itemName=eg2.vscode-npm-script) provides support for running `npm install` and `npm uninstall` commands from within VS Code. + +* [Auto Close HTML tag](https://marketplace.visualstudio.com/items?itemName=formulahendry.auto-close-tag) automatically adds HTML and XML closing tags. + +* [CSS IntelliSense (Completions)](https://marketplace.visualstudio.com/items?itemName=Zignd.html-css-class-completion) provides CSS class name completion for the HTML class attribute based on the CSS files in your workspace as well as React's `className` attribute. + +## React + +* A new [React Tutorial](https://code.visualstudio.com/docs/nodejs/reactjs-tutorial) shows you how to set up a React app from scratch, IntelliSense, Debugging, Linters, and more. + +## Angular + +* [Angular Language Service](https://marketplace.visualstudio.com/items?itemName=Angular.ng-template) provides a rich editing experience for Angular templates, both inline and external templates including completions lists, AOT diagnostic messages, quick info, and even Go To Definition. + +## Debugging + +* VS Code's [Node.js Debugging documentation](https://code.visualstudio.com/docs/nodejs/nodejs-debugging) explains how to configure VS Code for a variety of application types. + +* [Chrome Debugger](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) lets you debug your JavaScript code running in the Google Chrome browser or other targets that support the Chrome Debugging Protocol. + +* [Debugging configuration recipes](https://github.com/Microsoft/vscode-recipes) + +## Linters + +* [TSLint](https://marketplace.visualstudio.com/items?itemName=eg2.tslint) integrates the [tslint](https://github.com/palantir/tslint) linter for the TypeScript language into VS Code. + +* [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) integrates [ESLint](http://eslint.org/) (a pluggable linting utility for JavaScript and JavaScript React (JSX) into VS Code. + +## NoSQL MongoDB + +* The [MongoDB Extension](https://github.com/microsoft/vscode-mongodb) lets you connect to both local and hosted MongoDB databases, create and drop databases and collections, run queries, and more. To use the extension simply clone the repository, run `npm install`, and then press `F5` to run the extension in the development host. Alternatively, you can build the extension locally and then install it: + +``` javascript +npm install -g vsce +vsce package +code --install-extension vscode-mongodb-0.0.1.vsix +``` + +## Docker and Micro-Services + +* Install and learn more about [Docker](https://www.docker.com/). + +* The [Docker Tools for VS Code](https://marketplace.visualstudio.com/items?itemName=PeterJausovec.vscode-docker) make it easy to develop and deploy containerized micro-service based applications using Docker containers. + +* [Docker multi-stage builds](https://codefresh.io/blog/node_docker_multistage/) + +## Azure + +**Note:** If you do not have an Azure subscription, [sign up today](https://azure.microsoft.com/en-us/free/?b=16.48) for a **free** 30 day account and get **$200** in Azure Credits to try out any combination of Azure services. + +* The new cross platform [Azure CLI 2.0](https://aka.ms/GetTheAzureCLI). + +* [Azure CLI Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azurecli) provides a rich editing experience in VS Code for the [Azure CLI 2.0](https://aka.ms/GetTheAzureCLI). + +* [Cosmos DB](https://docs.microsoft.com/en-us/azure/cosmos-db/mongodb-introduction) let's you host your MongoDB databases in Azure. + +* [Kubernetes](https://kubernetes.io/) and [Kubernetes in Azure](https://docs.microsoft.com/en-us/azure/container-service/container-service-kubernetes-walkthrough). diff --git a/blogs/2017/06/20/font-ligatures-annotated.png b/blogs/2017/06/20/font-ligatures-annotated.png new file mode 100644 index 0000000000000000000000000000000000000000..c277f9dbf8ff6f20ef88891f82e0c96ae71e5300 Binary files /dev/null and b/blogs/2017/06/20/font-ligatures-annotated.png differ diff --git a/blogs/2017/06/20/great-looking-editor-roundup.md b/blogs/2017/06/20/great-looking-editor-roundup.md new file mode 100644 index 0000000000000000000000000000000000000000..bac0ae1285f51637a0a19e0a4481f71789c28d89 --- /dev/null +++ b/blogs/2017/06/20/great-looking-editor-roundup.md @@ -0,0 +1,71 @@ +--- +Order: 29 +TOCTitle: Fresh Paint +PageTitle: Fresh Paint - Give Visual Studio Code a New Look +MetaDescription: Give VS Code a new look with these popular extensions, color themes, file icon themes and more. +Date: 2017-06-20 +ShortDescription: Give VS Code a new look with these popular extensions, color themes, file icon themes and more. +Author: Wade Anderson +--- +# Fresh Paint - Give VS Code a New Look + +June 20, 2017 Wade Anderson, [@waderyan_](https://twitter.com/waderyan_) + +Having a great looking editor is a necessity for any full-time developer. We spend a lot of time in our editor and we like to keep things fresh and interesting! + +Visual Studio Code supports a lot of customizations, in particular the look of your environment. In this blog, we're going to look at [Color Themes](/docs/getstarted/themes.md), [File Icon Themes](/docs/getstarted/themes.md#icon-themes), and other [settings](/docs/getstarted/settings.md) to change the look and feel of the code editor. + +## Color Themes + +A powerful customization is the ability to change a Color Theme. A Color Theme is a set of colors for the editor background, text, language syntax, etc. VS Code comes with several built-in themes and there are hundreds you can install from the [Marketplace](https://marketplace.visualstudio.com/search?term=tag%3A%22color%20theme%22&target=VSCode&category=Themes&sortBy=Downloads). + +
+ +Some of the favorite themes used the VS Code team are **Sapphire**, **Nord** and **Ayu**, shown below. + +### Sapphire Theme + +Marketplace - [Sapphire Theme](https://marketplace.visualstudio.com/items?itemName=Tyriar.theme-sapphire) + +Author - [Daniel Imms](https://marketplace.visualstudio.com/search?term=publisher%3A%22Daniel%20Imms%22&target=VSCode&category=All%20categories&sortBy=Relevance) + +![sapphire color theme](themes-sapphire.gif) + +### Nord + +Marketplace - [Nord](https://marketplace.visualstudio.com/items?itemName=arcticicestudio.nord-visual-studio-code) + +Author - [arcticicestudio](https://marketplace.visualstudio.com/search?term=publisher%3A%22arcticicestudio%22&target=VSCode&category=All%20categories&sortBy=Relevance) + +![nord color theme](themes-nord.gif) + +### Ayu + +Marketplace - [Ayu](https://marketplace.visualstudio.com/items?itemName=teabyii.ayu) + +Author - [teabyii](https://marketplace.visualstudio.com/search?term=publisher%3A%22teabyii%22&target=VSCode&category=All%20categories&sortBy=Relevance) + +![ayu color theme](themes-ayu.gif) + +## File Icon Themes + +Using a File Icon Theme helps you quickly see file types in the Explorer and tabs through colorful icons. Here is a screenshot of supported icons from [VSCode Great Icons](https://marketplace.visualstudio.com/items?itemName=emmanuelbeziat.vscode-great-icons). + +![vscode great icons](vscode-great-icons.jpg) + +Just as with Color Themes, there are many popular File Icon Themes in the [Marketplace](https://marketplace.visualstudio.com/search?term=tag%3A%22icon%20theme%22&target=VSCode&category=Themes&sortBy=Downloads). + +
+ +## Font Ligatures + +There are many settings you can tweak to make VS Code look good. One of my favorites is font ligatures, where two characters are combined into a single expressive character. Enable font ligatures by setting `"editor.fontLigatures"` to `true`. You must have a font installed that supports font ligatures, such as [Fira Code](https://github.com/tonsky/FiraCode). + +![font ligatures](font-ligatures-annotated.png) + +## How do you make your editor look good? + +What do you do to make your editor look good? Ping me on [Twitter](https://twitter.com/waderyan_) and I'd love to share your tips in a future blog post. + +Wade Anderson, VS Code Team Member +[@waderyan_](https://twitter.com/waderyan_) diff --git a/blogs/2017/06/20/themes-ayu.gif b/blogs/2017/06/20/themes-ayu.gif new file mode 100644 index 0000000000000000000000000000000000000000..ee760ad31af3c2040a25e21fbbf8947880cb5ba8 --- /dev/null +++ b/blogs/2017/06/20/themes-ayu.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d7e70c0d0cfbb1377796214c7646e426e8811d4f6c7bc9106844d492f51c895a +size 491358 diff --git a/blogs/2017/06/20/themes-nord.gif b/blogs/2017/06/20/themes-nord.gif new file mode 100644 index 0000000000000000000000000000000000000000..d59b617316b2a91980f62ae102db33f091e5821d --- /dev/null +++ b/blogs/2017/06/20/themes-nord.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9b10872fde22ebf6d9d72f1b6352a78078ca15bdacef9a1cd65a67b1a86b82a1 +size 125952 diff --git a/blogs/2017/06/20/themes-sapphire.gif b/blogs/2017/06/20/themes-sapphire.gif new file mode 100644 index 0000000000000000000000000000000000000000..b219709638f6ae2eed3d150420c04fd6b17587c1 --- /dev/null +++ b/blogs/2017/06/20/themes-sapphire.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:aa10d96210ca94a92795689f1437b08435e4964b09c98df282fc76b1bbe40991 +size 550285 diff --git a/blogs/2017/06/20/vscode-great-icons.jpg b/blogs/2017/06/20/vscode-great-icons.jpg new file mode 100644 index 0000000000000000000000000000000000000000..af6fb078751177e5bb991f0dbb1447bb49907cc1 --- /dev/null +++ b/blogs/2017/06/20/vscode-great-icons.jpg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2600b014a1c979b8ab162e1352f102a11ff41d15a036b501240f79bd30675c02 +size 150667 diff --git a/blogs/2017/08/07/emmet-2.0.md b/blogs/2017/08/07/emmet-2.0.md new file mode 100644 index 0000000000000000000000000000000000000000..d9e1b9ee49523faa9c9e972f8fd0fbd62bd67fb1 --- /dev/null +++ b/blogs/2017/08/07/emmet-2.0.md @@ -0,0 +1,97 @@ +--- +Order: 30 +TOCTitle: Emmet 2.0 +PageTitle: Emmet 2.0 in Visual Studio Code +MetaDescription: New Emmet 2.0 brings a better Emmet experience inside VS Code. +Date: 2017-08-07 +ShortDescription: New Emmet 2.0 brings a better Emmet experience inside VS Code. +Author: Ramya Rao +--- +# Emmet 2.0 in Visual Studio Code + +August 7, 2017 Ramya Rao, [@ramyanexus](https://twitter.com/ramyanexus) + +In the July 2017 release of Visual Studio Code (version 1.15), we're shipping a better Emmet experience which has been in preview for the past 2 releases. + +Its features include: + +* Emmet abbreviation expansions in suggestion/auto-completion lists. +* Multi-cursor support for most [Emmet actions](https://docs.emmet.io/actions/). +* Updated support for custom Emmet snippets. + +![Emmet in suggestion/auto-completion list](emmet.gif) + +As part of this update, we have re-written all of the Emmet actions using new npm modules from [@emmetio](https://www.npmjs.com/~emmetio). + +An important change is that the `kbstyle(Tab)` key is no longer the default way to expand Emmet abbreviations. Instead, Emmet abbreviations will now appear in the suggestion list. They can be selected like any other smart completion and on selection, the abbreviation will be expanded. + +>**Note**: To continue to expand Emmet abbreviations and snippets using the `kbstyle(Tab)` key, set `emmet.triggerExpansionOnTab` to `true`. + +Read on to learn about the Emmet 2.0 changes in Visual Studio Code. + +## New modular approach to Emmet + +Previously, the [Emmet library](https://github.com/emmetio/emmet) was a single monolithic codebase that was used for every [Emmet action](https://docs.emmet.io/actions/). The author of Emmet, [Sergey Chikuyonok](https://github.com/sergeche), envisioned a new world for Emmet 2.0 with smaller, re-usable modules. + +There are now separate npm modules from [@emmetio](https://github.com/emmetio) for the different parts of the pipeline required to expand an Emmet abbreviation. These include steps such as: + +* Parsing an abbreviation +* Resolving snippets and variables +* Rendering output as per syntax +* Applying transformations + +There are also separate modules for parsing HTML and CSS documents to aid in implementing the rest of the Emmet features. You can find these modules on npm under [emmetio](https://www.npmjs.com/~emmetio). + +This modular approach was taken to allow editor plugins to use the editor specific APIs for better Emmet integration with the editor features. For example, this approach has allowed us to: + +* Provide Emmet abbreviation expansions in the suggestion/auto-completion list. +* Provide multi cursor support for most of the Emmet actions. +* Provide more efficient parsing of documents using VS Code specific APIs for Emmet actions that need parsed files. +* Pull the Emmet integration out of the VS Code core and into an extension. + +## Tab no longer the default Emmet expansion key + +There were two issues with using the `kbstyle(Tab)` key as a keyboard shortcut for Emmet expansion: + +* Emmet expansions occurred when the user wanted to indent source code using the `kbstyle(Tab)` key. +* Items from the suggestion list were inserted when the user wanted to expand an Emmet abbreviation. + +[Sergey Chikuyonok](https://github.com/sergeche) realized that having Emmet in the suggestion list would be a more pleasant experience. That it helped us solve the above two issues, was an added bonus. + +With Emmet abbreviations now easily accessible via suggestion list, we were able to remove the default association of `kbstyle(Tab)` key with the **Emmet: ExpandAbbreviation** command. The `kbstyle(Tab)` key is now free to do what it was meant to do: indent. + +If you have the `editor.quickSuggestions` [setting](/docs/getstarted/settings.md) turned off, you will have to press `kb(editor.action.triggerSuggest)` to trigger the suggestion/auto-completion list manually. + +If you don't want Emmet showing up in the suggestion/auto-completion list, set `emmet.showExpandedAbbreviation` to `never`. + +You can still bind any keyboard shortcut (other than `kbstyle(Tab)` key) to the `editor.emmet.action.expandAbbreviation` command or use **Emmet: Expand Abbreviation** from the **Command Palette**. + +If you prefer the `kbstyle(Tab)` key for expanding your abbreviations, then add the setting `emmet.triggerExpansionOnTab` to your settings and set it to `true`. We use this setting to provide the appropriate fallback to provide indentation when there is no abbreviation to expand. + +## Other changes + +There are a few other changes that we have documented in the new Emmet [page](/docs/editor/emmet.md): + +* Use `emmet.includeLanguages` instead of `emmet.syntaxProfiles` setting to [enable Emmet in other file types](/docs/editor/emmet.md#emmet-abbreviations-in-other-file-types) +* Changes to how you write [custom snippets in Emmet](/docs/editor/emmet.md#using-custom-emmet-snippets) +* Changes to available [Emmet settings](/docs/editor/emmet.md#emmet-configuration) +* To wrap individual lines in a single selection in separate tags, use the command **Emmet: Wrap Individual Lines with Abbreviation** instead of **Emmet: Wrap with Abbreviation**. +* [Known issues in Emmet 2.0](/docs/editor/emmet.md#known-issues-in-emmet-20) that we are working on in August 2017 + +## People who made Emmet 2.0 happen + +I want to thank [Sergey Chikuyonok](https://github.com/sergeche) for his amazing work on modularizing Emmet and helping us bring these improvements to VS Code. + +Thanks also goes to everyone who used the new Emmet in VS Code when it was in preview and provided great feedback through GitHub issues. The discussions in Github issues were very helpful in getting to the current user experience. + +Special thanks to [Steve Lombardi](https://github.com/smlombardi), [Jens Hausdorf](https://github.com/jens1o), [Vladimir Sizikov](https://github.com/vvs), [Niichie](https://github.com/Niichie), [Thomas Klepzig](https://github.com/tklepzig) and many more who used the VS Code Insiders builds to test my bug fixes and feature additions. + +## Share your thoughts on the new Emmet + +Do you miss any features of the old Emmet? Having trouble using the new Emmet? Feel free to create an GitHub [issue](https://github.com/Microsoft/vscode/issues) and we will do our best to help you out. + +It is also easier than ever to contribute to Emmet in VS Code as it is now an extension. The [emmet folder](https://github.com/Microsoft/vscode/tree/master/extensions/emmet) in the VS Code GitHub repo has all the source code you need to get started. + +Happy Coding! + +Ramya Rao, VS Code Team member [@ramyanexus](https://twitter.com/ramyanexus) diff --git a/blogs/2017/08/07/emmet.gif b/blogs/2017/08/07/emmet.gif new file mode 100644 index 0000000000000000000000000000000000000000..40a58546127ce4a094471923adc15dedca6c085c --- /dev/null +++ b/blogs/2017/08/07/emmet.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:82f194f2b74764015768c47308feeaec03ef3484242357d2d870a2e38a20a117 +size 194330 diff --git a/blogs/2017/09/28/debug-features.png b/blogs/2017/09/28/debug-features.png new file mode 100644 index 0000000000000000000000000000000000000000..253ff23d81d7cd0d25ba3579d06b570c1c4d392c Binary files /dev/null and b/blogs/2017/09/28/debug-features.png differ diff --git a/blogs/2017/09/28/java-debug-extension.png b/blogs/2017/09/28/java-debug-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..eb5c5724c86a1928b8f1c2d09defa6ab055795dc Binary files /dev/null and b/blogs/2017/09/28/java-debug-extension.png differ diff --git a/blogs/2017/09/28/java-debug.gif b/blogs/2017/09/28/java-debug.gif new file mode 100644 index 0000000000000000000000000000000000000000..1a3cf5735a549718ee080f70ceb9dbc2c16078fb --- /dev/null +++ b/blogs/2017/09/28/java-debug.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:81b0a4ae8a3b98ff8f30c125000cc446221791827c6bd5532237d346e8196062 +size 1694905 diff --git a/blogs/2017/09/28/java-debug.md b/blogs/2017/09/28/java-debug.md new file mode 100644 index 0000000000000000000000000000000000000000..21ac3d8ea52d6ec31672f3ef51a490949644adf3 --- /dev/null +++ b/blogs/2017/09/28/java-debug.md @@ -0,0 +1,68 @@ +--- +Order: 31 +TOCTitle: Java Debugging +PageTitle: Using Visual Studio Code to Debug Java Applications +MetaDescription: Java Development with VS Code +Date: 2017-09-28 +ShortDescription: Using VS Code to Debug Java Applications +Author: Xiaokai He +--- +# Using VS Code to Debug Java Applications + +September 28, 2017 Xiaokai He + +For Java developers on Visual Studio Code, the [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) extension has been great for providing language features such as IntelliSense and project support. At the same time, we've also heard feedback that users would also like Java debugging. Today, we're excited to announce our ongoing collaboration with Red Hat and enabling Java developers to debug Java applications with a new lightweight [Java Debugger for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) based on [Java Debug Server](https://github.com/Microsoft/java-debug). + +![Java debug extension](java-debug-extension.png) + +>**Note**: Both the **Java Debugger for Visual Studio Code** and **Java Debug Server** will be open sourced shortly after the initial release. + +To help Java developers to get started with VS Code quickly, we also created a [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack) which includes both the [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) and [Java Debugger for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) extensions so you won't need to search for them individually. This is just the start to creating a modern workflow for Java and we'll be adding more features and extensions to the **Java Extension Pack** in the future. + +![Java extension pack](java-extension-pack.png) + +## Getting started + +To get started: + +1. In Visual Studio Code, open the **Extensions** view (`kb(workbench.view.extensions)`). +2. Type "java" to filter the list. +3. Find and install the [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack) or standalone [Java Debugger for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) extension if you already have [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) installed. + +You also install the **Java Extension Pack** directly from this blog post: + +Install the Java Extension Pack + +After reloading VS Code, open a folder that contains a Java project and follow below steps: + +1. Prepare the project. Open a `.java` file, and the Java extensions will be activated. Maven, Gradle and Eclipse projects are supported. Project build is automatically handled by the extensions, no need to be triggered manually. +2. Start debugging. Switch to **Debug** view (`kb(workbench.view.debug)`) and open `launch.json` to add a debug configuration for Java. +3. Fill in the `mainClass` for `Launch` setting or `hostName` and `port` for `Attach`. +4. Set your breakpoint and hit `F5` to start debugging. + +![Debugging Java Application](java-debug.gif) + +## Supported features + +In this release, we support the following features: + +- **Launch/Attach** - You can either launch the Java project within VS Code or attach to any running JVM process in debug mode, locally or remotely. +- **Breakpoints** - Conditional breakpoints by Hit Count is supported and can easily be set using the inline breakpoint settings window. This allows you to conveniently add conditional breakpoints to your code, directly in the source viewer, without requiring a modal window. Break on exceptions is also supported. +- **Control flow** - Including **Pause**, **Continue** `F5`, **Step over** `F10`, **Step into** `F11`, **Step out** `Shift+F11` +- **Data inspection** - When you're stopped at a breakpoint, the debugger has access to the variable names and values that are currently stored in memory. Inspect/Watch/Set Variables are supported. +- **Diagnostics** - The **CALL STACK** panel shows the call stack of your program and allows you to navigate through the call path of each captured allocation. Multi-threaded debugging is supported by parallel stacks. +- **Debug Console** - The Debug Console lets you see information from both stdout and stderr. + +![Debugging Features](debug-features.png) + +Future releases will include expression evaluation and hot code replacement. + +## Next Steps + +- Checkout more about [Java on VS Code](/docs/languages/java.md) + +## Feedback + +Please share your feedback and ask questions to help us improve. You can contact us on [Gitter](https://gitter.im/Microsoft/vscode-java-debug). + +Xiaokai He, [@JavaOnAzure](https://twitter.com/JavaOnAzure) \ No newline at end of file diff --git a/blogs/2017/09/28/java-extension-pack.png b/blogs/2017/09/28/java-extension-pack.png new file mode 100644 index 0000000000000000000000000000000000000000..4b4c9977afb3aa402d1079cdfd81f41b16c84fc8 Binary files /dev/null and b/blogs/2017/09/28/java-extension-pack.png differ diff --git a/blogs/2017/10/03/60fps.gif b/blogs/2017/10/03/60fps.gif new file mode 100644 index 0000000000000000000000000000000000000000..5d5b90b4c6e923e76371227e48a3f8270c80c182 --- /dev/null +++ b/blogs/2017/10/03/60fps.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f9f6ffe899f207ed10dcb364a2eef8ed7295613aa706173a448a8af18b9dc727 +size 3940464 diff --git a/blogs/2017/10/03/misaligned.png b/blogs/2017/10/03/misaligned.png new file mode 100644 index 0000000000000000000000000000000000000000..a88397e30a99dbbb8f02162b36302940e177bb49 Binary files /dev/null and b/blogs/2017/10/03/misaligned.png differ diff --git a/blogs/2017/10/03/paint-flashing.gif b/blogs/2017/10/03/paint-flashing.gif new file mode 100644 index 0000000000000000000000000000000000000000..165618c6645606682660474ff5efdaae8ed823f5 --- /dev/null +++ b/blogs/2017/10/03/paint-flashing.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e8cecca163edb3f8291469fcb2786f4f71b1ba12c193e969ffce20f69f354abf +size 251126 diff --git a/blogs/2017/10/03/terminal-renderer.md b/blogs/2017/10/03/terminal-renderer.md new file mode 100644 index 0000000000000000000000000000000000000000..fef26b52e71db166f1e86aacdf58c3e5e692f7ad --- /dev/null +++ b/blogs/2017/10/03/terminal-renderer.md @@ -0,0 +1,85 @@ +--- +Order: 32 +TOCTitle: Integrated Terminal Performance +PageTitle: Integrated Terminal Performance Improvements +MetaDescription: Explore the performance improvements made to Visual Studio Code's integrated terminal renderer in version 1.17 +Date: 2017-10-03 +ShortDescription: Explore the performance improvements made to Visual Studio Code's integrated terminal renderer in version 1.17 +Author: Daniel Imms +--- +# Integrated Terminal Performance Improvements + +October 3, 2017 Daniel Imms, [@Tyriar](https://twitter.com/Tyriar) + +The rendering engine of the Integrated Terminal has been completely re-written with performance in mind for the upcoming version 1.17 of Visual Studio Code. In this version, we move away from a DOM-based rendering system to using the HTML [canvas](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas) element. + +## DOM Rendering + +It's somewhat surprising, but rendering an interactive terminal was possible in a system designed for displaying static documents. However, as time went on we found that certain functionality provided by the DOM needed to be overridden to fix several issues: + +**Selection**: There was a lot of working against the DOM's selection system to cover the terminal use case. Since we always rendered only what was visible to the DOM, you could not select multiple pages of content without reimplementing selection. Scrolling would also cause the selection to be dropped. In order to resolve these issues, custom selection logic was added in VS Code version [1.14](https://code.visualstudio.com/updates/v1_14#_selection-reimplemented). + +**Misaligned characters**: Due to many monospace fonts not being strictly monospace for some Unicode characters, this could lead to situations like the one seen on the right-side of the image below: + +![Characters to the right of the terminal could become misaligned when Unicode was used](misaligned.png) + +A workaround for this would be to wrap all Unicode characters in fixed width spans, however this increases the time it takes to render a frame. + +**Excessive garbage collection**: Due to the number of elements needed to render the terminal, the garbage collector needed to clean up memory frequently, often pushing out rendering time by a noticeable amount. An object pool was put in place to try to work around this problem, allowing DOM elements to be recycled. + +**Performance**: No matter how hard we try to resolve these issues, performance will always have the hard cap imposed by the layout engine. + +## Sidestepping the Layout Engine + +In some cases, composing elements and doing a layout could take longer than a frame (16.6ms) all by itself, which is unacceptable if we want to maintain a smooth 60 frames per second (FPS) in the terminal. The solution for this was a new canvas-based rendering engine. + +The [`` HTML element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas) allows drawing graphics and text using a JavaScript API. + +## Render Layers + +A number of canvas elements known as "render layers" are used to simplify the rendering of different parts of the terminal. + +The current layers, in order, are: + +1. **Text**: Background colors and foreground text, this layer is opaque. +2. **Selection**: Selection using the mouse. +3. **Link**: The underline when hovering over links. +4. **Cursor**: The terminal's cursor. + +Separating these parts out into their own little components has vastly simplified how drawing is done. + +## Only Draw What Changed + +An important part of the new renderer is that it only draws what has *changed*. To do so, a slim internal model is kept which contains the minimal amount of information about a cell's drawn state. The state is then used to quickly check when a cell needs to change before the more expensive draw action is performed. In the case of the **Text** layer, this model includes a reference to the character, text styles, foreground color and background color. + +This is compared to the previous rendering engine where the entire line would be removed from the DOM, reconstructed and re-added, even when nothing changed. + +![Only individual character changes are now drawn to the screen](paint-flashing.gif) + +*The green rectangles in the image above indicate the regions that are redrawn.* + +## The Texture Atlas + +A texture atlas is used to boost rendering time even further. There is an [`ImageBitmap`](https://developer.mozilla.org/en-US/docs/Web/API/ImageBitmap) behind the scenes which contains all ASCII characters in the most common styles on the default background color. + +When drawing these styles of text, the texture atlas is used instead of a regular call to [`CanvasRenderingContext2D.fillText`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/fillText). As the `ImageBitmap` is co-located on the GPU, the speed of drawing is improved considerably. + +![Behind the scenes an image is maintained containing the most common characters](texture-atlas.png) + +## Forced Frame Skipping + +Due to the speed of rendering in the DOM, it was necessary to skip extra frames in order to ensure the parser had enough CPU time. While this enabled commands to run faster than before, a lot of data being streamed through the terminal would cause the frame rate to drop below 10 FPS. + +With the new renderer, this restriction has been removed and you can now enjoy up to 60 FPS in the terminal. + +![60 frames per second is now possible in the terminal](60fps.gif) + +## The Results + +Our benchmarks have measured that the Integrated Terminal now renders approximately **5 to 45 times faster than before**, depending on the situation. Even if you don't notice the increased responsiveness and frame rate, faster rendering also means less battery usage! We hope you enjoy the performance improvements, they are coming to version 1.17 of VS Code in a few days and are available to test in the [Insiders build](https://code.visualstudio.com/insiders) right now. + +You can also jump into the [original xterm.js pull request](https://github.com/sourcelair/xterm.js/pull/938) that added the feature for a more detailed look. + +Happy Coding! + +Daniel Imms, VS Code Team member [@Tyriar](https://twitter.com/Tyriar) diff --git a/blogs/2017/10/03/texture-atlas.png b/blogs/2017/10/03/texture-atlas.png new file mode 100644 index 0000000000000000000000000000000000000000..32565f6dc73148b2fa68bb6624ef519ab13bed88 --- /dev/null +++ b/blogs/2017/10/03/texture-atlas.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dd36924c77e0e0ae5bbfd92227f36dbc87d4c7dd0c9c2897a077534fc9b7e1a8 +size 281555 diff --git a/blogs/2017/10/24/blueicon.png b/blogs/2017/10/24/blueicon.png new file mode 100644 index 0000000000000000000000000000000000000000..a5712192ab5b43b40c9885055166260c30747426 Binary files /dev/null and b/blogs/2017/10/24/blueicon.png differ diff --git a/blogs/2017/10/24/colorrecognition.png b/blogs/2017/10/24/colorrecognition.png new file mode 100644 index 0000000000000000000000000000000000000000..3495168579411a0c6979c8d8208fd6ea8bb2970e Binary files /dev/null and b/blogs/2017/10/24/colorrecognition.png differ diff --git a/blogs/2017/10/24/earlydesigns.png b/blogs/2017/10/24/earlydesigns.png new file mode 100644 index 0000000000000000000000000000000000000000..ecbbc71dfd9fdd930b248fdaff6d67c716ea946f Binary files /dev/null and b/blogs/2017/10/24/earlydesigns.png differ diff --git a/blogs/2017/10/24/editorlinesicon.png b/blogs/2017/10/24/editorlinesicon.png new file mode 100644 index 0000000000000000000000000000000000000000..ac959c2768e3183b8842179a99b5716e2dae8bb9 Binary files /dev/null and b/blogs/2017/10/24/editorlinesicon.png differ diff --git a/blogs/2017/10/24/hurtsmyeyes.png b/blogs/2017/10/24/hurtsmyeyes.png new file mode 100644 index 0000000000000000000000000000000000000000..34b4445222e793b075cf5625ca21d5acd5d132e1 Binary files /dev/null and b/blogs/2017/10/24/hurtsmyeyes.png differ diff --git a/blogs/2017/10/24/insidersgreen.png b/blogs/2017/10/24/insidersgreen.png new file mode 100644 index 0000000000000000000000000000000000000000..5b3a34d009e75417ffc6644ec0b2e52c742444dc Binary files /dev/null and b/blogs/2017/10/24/insidersgreen.png differ diff --git a/blogs/2017/10/24/insidersgreenwindows.png b/blogs/2017/10/24/insidersgreenwindows.png new file mode 100644 index 0000000000000000000000000000000000000000..baa067d470e9e3d8cc6f43fac3975d0963f95605 Binary files /dev/null and b/blogs/2017/10/24/insidersgreenwindows.png differ diff --git a/blogs/2017/10/24/newvscodeiconuglyissue.png b/blogs/2017/10/24/newvscodeiconuglyissue.png new file mode 100644 index 0000000000000000000000000000000000000000..80921e8b26499c7f5589defb167a2922b24dae9c Binary files /dev/null and b/blogs/2017/10/24/newvscodeiconuglyissue.png differ diff --git a/blogs/2017/10/24/orangeprerelease.png b/blogs/2017/10/24/orangeprerelease.png new file mode 100644 index 0000000000000000000000000000000000000000..82d01df3b6f935bb93ee48fbd868e5f3d4d95104 Binary files /dev/null and b/blogs/2017/10/24/orangeprerelease.png differ diff --git a/blogs/2017/10/24/originalblueicon.png b/blogs/2017/10/24/originalblueicon.png new file mode 100644 index 0000000000000000000000000000000000000000..06b3a6087e4ceaefac34b0ffc6cdff0a0bc77146 Binary files /dev/null and b/blogs/2017/10/24/originalblueicon.png differ diff --git a/blogs/2017/10/24/outlines.png b/blogs/2017/10/24/outlines.png new file mode 100644 index 0000000000000000000000000000000000000000..6efba2f777d313c84543fbd9c05129a2e8ab2558 Binary files /dev/null and b/blogs/2017/10/24/outlines.png differ diff --git a/blogs/2017/10/24/stablewithblue.png b/blogs/2017/10/24/stablewithblue.png new file mode 100644 index 0000000000000000000000000000000000000000..680ddc69b0c0e4da6a2873a8d150ecd47a06aa8c --- /dev/null +++ b/blogs/2017/10/24/stablewithblue.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6d498e585e5e9c67ee2d05e0d0d9faea882d1cfb636e1589f4d9eee728328c76 +size 172545 diff --git a/blogs/2017/10/24/theicon.md b/blogs/2017/10/24/theicon.md new file mode 100644 index 0000000000000000000000000000000000000000..44d573d9e69c526415ed7259a22d084ff2fa9cef --- /dev/null +++ b/blogs/2017/10/24/theicon.md @@ -0,0 +1,150 @@ +--- +Order: 33 +TOCTitle: The Icon Journey +PageTitle: The Icon Journey +MetaDescription: Summary of feedback about the new icons and next steps +MetaSocialImage: /assets/blogs/2017/10/24/blueicon.png +Date: 2017-10-24 +ShortDescription: Summary of feedback about the new icons and next steps +Author: Chris Dias +--- +# The Icon Journey + +October 24, 2017 Chris Dias, [@chrisdias](https://twitter.com/chrisdias) + +## TL;DR + +Thanks for all the passionate feedback. It has been very helpful, painful, and entertaining all at the same time. We're changing the orange icon to blue for Stable and keeping green for Insiders. + +![Windows and macOS stable blue icon](blueicon.png) + +## What is your favorite color? + +In [Monty Python and the Holy Grail](https://en.wikipedia.org/wiki/Monty_Python_and_the_Holy_Grail), the bridge keeper asks Sir Lancelot three questions before allowing him to cross the Bridge of Death. Answer all three correctly and Sir Lancelot can pass. Answer incorrectly and it's an untimely death. [Sir Lancelot answered blue when asked his favorite color and was allowed to cross](https://www.youtube.com/watch?v=qry9IeJnbNU). + +We answered "orange". + +## Apologies and Transparency + +First, an apology for the delay in responding. We've been watching the feedback come in, we've read every single piece, and we've been having "lively" discussions on the next steps. We believe we have a rational plan and want to share it with you, and we look forward to a continuing dialog on what we now know is such a deeply controversial topic. + +For complete transparency, we want to share some history as we think it helps to understand how we arrived at orange in the first place. + +## Welcome to the family + +Back in [March](https://devblogs.microsoft.com/visualstudio/iterations-on-infinity), we (the broader Visual Studio team) set out to create a "family" feel across all of the developer tools we produce. If you read that blog post again, you can see that we had to work within a set of "challenging" corporate branding guidelines (for example, a single color). + +It is easy to blame the guidelines, but at the same time, having a set of products that are easily and broadly recognizable is a valuable asset. Instead, we took on the challenge of working within the constraints while also working across the company to evolve the guidelines and address the problems we faced. + +When we saw the negative feedback from the initial set of icons, we went heads down on the VS Code icon. We wanted to produce an icon that both the broad community and we would find instantly, visually, and emotionally appealing. + +Here are some of the early designs: + +![Early VS Code icon designs](earlydesigns.png) + +None of these really stood out for us, except the one in the upper right corner. + +![Early VS Code icon designs](editorlinesicon.png) + +This was rejected because it didn't contain any folds, which is a component of the family design. Back to the drawing board. + +We iterated on the infinity logo for some time, for example: + +![Variations on the infinity design](variationsoninfinity.png) + +Including one that will hurt your eyes: + +![A variation that hurts the eyes](hurtsmyeyes.png) + +Until we landed on the current "fish", which tested well with admittedly, a small number of developers. + +## Rotation + +We have a lot more design freedom on the macOS (and Linux), which is why we have a different icon there. While we wanted to keep the same icon shape, we were not limited to a single color and we could resolve contrast issues by mounting the icon on a dark panel. The rotation actually adheres to the [Apple design guidelines](https://developer.apple.com/macos/human-interface-guidelines/icons-and-images/app-icon). + +That said, the feedback that the rotation is outdated and the mount makes the icon appear smaller than other icons in the Dock is completely fair. + +## Fatigue + +By mid-summer, icon fatigue rolled in. We had made so many iterations, we finally said let's go with the current shape, and we checked in the "pre-release" design for Insiders. A pre-release is denoted by the hashed box on the right and bottom: + +![Pre-release icons in orange](orangeprerelease.png) + +The hash looks great at large sizes (for example on a PowerPoint slide), but at small sizes the box is very washed out and the icon becomes blurry. We iterated on a number of outlines in white, black, and different shades of orange and green. Here they are enlarged to see the edges. + +![Border iterations](outlines.png) + +To combat this problem, we also tried the macOS version on Windows and that simply looked out of place, and even worse at small sizes. In the end, we decided to drop the pre-release design and use a different color for Insiders. Green was available, and it was the existing Insiders color, so we went with that. + +Voila, Insiders: + +![Insiders with the green macOS icon](insidersgreenwindows.png) + +## Icon Squatting + +Before VS Code existed, there was [Visual Studio Online Monaco](https://azure.microsoft.com/en-us/resources/videos/building-web-sites-with-visual-studio-online-monaco/), which was our fully browser based workbench that lets you live edit your Azure App Service web apps. Since we were calling ourselves "Visual Studio Online" and needed an icon, we "borrowed" the blue infinity. + +When we first released VS Code, everything was happening so quickly, and the icon was the least of our concerns. Regardless of what you think about the new icon, [the old one looks pretty bad](https://github.com/Microsoft/vscode/issues/11274) on the desktop and in the Taskbar and Dock, it was really meant to be a favicon. + +![Original blue infinity icon](originalblueicon.png) + +Later on, when we decided that each product in the family would have its own color, and since blue was already taken, we'd have to come up with something else. Plus, we stole it from them, so it seemed right to give it back :). + +## Pumpkin Spice + +At this point, we pretty much ran out of colors in the family palette, except for the now infamous orange. There was some concern about the similarity to Sublime Text color palette, but no one had issues when we tested it. And quite honestly, we were more surprised by the latest Sublime's use of a folded ribbon. + +## How to generate a lot of feedback...quickly + +The Insiders builds had the orange and then green icons for about 2 months as we iterated on the problems outlined above, and there wasn't a lot of negative feedback coming in. + +Maybe our fears were unfounded. Maybe users would really like the new icons and all the angst on a handful of problems were not worth losing sleep over. We decided not to shine a light on something that might not be a problem. We pushed the changes and made a [small reference to the new icons in the release notes](https://code.visualstudio.com/updates/v1_17#_new-visual-studio-code-logo). + +And then the issues and comments started rolling in. + +![GitHub Issue 35683](newvscodeiconuglyissue.png) + +![GitHub issue 35783](vscodenewlogoissue.png) + +(I must give credit to the author named "[badass-icon](https://github.com/badass-icon)", I see what you did there, well played.) + +Each day there were additional comments, each expressing a dislike of the new icon in new and interesting ways. After the first couple of days, we thought the feedback would slow and we would be able to address the individual issues. Turns out, we were wrong. The feedback just kept coming in. New issues were opened, comments came in faster than we could respond. Hacker News, Visual Studio Magazine. High School friends posted comments on FaceBook. Awesome. + +## You're my boy, Blue! + +And that brings us to today. + +We've reviewed all of the feedback from the breadth of issues opened and commented upon since we released 1.17.0 where we introduced the orange icon for Stable. It is clear that the [Halloween release](https://github.com/Microsoft/vscode/issues/35783#issuecomment-337200769) of VS Code didn't work well for a lot of you, and for that we apologize. + +Coincidentally as I write this, [mdb07a](https://github.com/mdb07a) did a nice job [summarizing the feedback and issues on Windows](https://github.com/Microsoft/vscode/issues/35783#issuecomment-338432169). I'm paraphrasing and there are more issues, but the top issues are: + +- The color change was far too drastic, orange is the opposite color of blue, making that which looked good before, look horrible now. +- A flat single color icon that relies entirely on transparency to create negative space makes it less distinct and aggravates the distinguishability problems. +- The new border is so large and bold that it's more distinct to the eye than the infinity symbol is. + +On macOS, the most prevalent feedback is that the tilt looks outdated and makes the important parts of the icon look small compared to other icons in the Dock. + +All of this feedback urged us go back and see if we could do a better job while still creating a family of products. As a result, we are going change the Stable icon to the much-loved blue. + +![Blue stable icons](blueicon.png) + +Which works well with the Status Bar and other blues in the editor: + +![Stable drop of VS Code with the blue icon](stablewithblue.png) + +For folks that have difficulty seeing the difference between Stable and Insiders, the green and blue work better together. Here's the two icons using the [Sim Daltonism](https://michelf.ca/projects/sim-daltonism/) app (Deuteranomaly): + +![Screen shot of Sim Daltonism app with the Deuteranomaly effect](colorrecognition.png) + +It is inevitable that we will have multiple products that share colors, so we are no longer concerned that VS Code shares the blue color. + +We are [exploring using a non-tilted icon for macOS]( https://github.com/Microsoft/vscode/issues/36692) based on @donysukardi's comment [here](https://github.com/Microsoft/vscode/issues/6607#issuecomment-335664326). We can't say yet that we'll do this, but we are going to explore it and either way, we'll post updates in that issue. + +## Looking Ahead + +Changing from orange to blue doesn't address all of the issues, however it is a step forward. We do expect the iconography to continue to evolve and are open to new ideas for VS Code within the family. + +We've learned a hard lesson about how to evolve and roll out icon changes, so thank you. For those who loved the orange icon, we hope you like blue even better. + +Thanks, +Chris diff --git a/blogs/2017/10/24/variationsoninfinity.png b/blogs/2017/10/24/variationsoninfinity.png new file mode 100644 index 0000000000000000000000000000000000000000..7b8b333263642f0937c38a80cd624f3b5a72c0d8 Binary files /dev/null and b/blogs/2017/10/24/variationsoninfinity.png differ diff --git a/blogs/2017/10/24/vscodenewlogoissue.png b/blogs/2017/10/24/vscodenewlogoissue.png new file mode 100644 index 0000000000000000000000000000000000000000..5e253e5542163c78bf669711e5819bf5c7ebd100 Binary files /dev/null and b/blogs/2017/10/24/vscodenewlogoissue.png differ diff --git a/blogs/2017/11/15/live-share.md b/blogs/2017/11/15/live-share.md new file mode 100644 index 0000000000000000000000000000000000000000..07596bec4b60ba51c99f2663160dce0179079832 --- /dev/null +++ b/blogs/2017/11/15/live-share.md @@ -0,0 +1,52 @@ +--- +Order: 34 +TOCTitle: Introducing Live Share +PageTitle: Introducing Visual Studio Live Share +MetaDescription: Real-time collaborative development +MetaSocialImage: /assets/blogs/2017/11/15/ls-social-resized.png +Date: 2017-11-15 +ShortDescription: Real-time collaborative development +Author: Amanda Silver +--- +# Introducing Visual Studio Live Share + +November 15, 2017 Amanda Silver, [@amandaksilver](https://twitter.com/amandaksilver) + +>**Update (May 7, 2018):** Visual Studio Live Share is now publicly available. You can [get started using Live Share](https://visualstudio.microsoft.com/services/live-share) today! + +We are excited to announce that we’re working on “Visual Studio Live Share”, which enables developers using Visual Studio 2017 or Visual Studio Code to collaborate in real-time! Learn more about Live Share and the upcoming limited private preview [here](/visual-studio-live-share). + +## What is Live Share? +Live Share enables your team to quickly collaborate on the same codebase without the need to synchronize code or to configure the same development tools, settings, or environment. + +When it comes to Live Share, seeing is believing. Watch the following video to get an idea of what we are working on: + + + +When you share a collaborative session, your teammate sees the context of the workspace in their editor. This means your teammate can read the code you shared without having to clone a repo or install any dependencies your code relies on. They can use rich language features to navigate within the code; not only just opening other files as text but using semantic analysis-based navigation like Go to Definition or Peek. + + +![Live Sharing with VS Code](vs-code-ls-session.png) + +When your teammate edits a file, they get editor enhancements like IntelliSense, statement completion, and suggestions. Each of you can open files, navigate, edit code, highlight, or refactor - and changes are instantly reflected. As you edit you can see your teammate’s cursor, jump to the location of your teammate’s carat, or follow their actions. + +Collaborative debugging goes further, allowing you and your teammate to independently inspect objects using debugging features like hovers, locals and watches, the stack trace or the debug console. You are both able to set breakpoints and advance the debug cursor to step through the session. + + +![Live Sharing with VS Code](vs-code-ls-session2.png) + +## Why Live Share? +While Microsoft Teams and Slack bring dynamic team collaboration into a digital form, there is more we can do to make it easier to work together in a development team. Screen-sharing or accessing a machine remotely means that only one person is in control while the other observes. Instant messaging, email, or other tools are great for basic messages but collaborating on a body of code often requires more than a code snippet or a single file to share the necessary context. Additionally, the validity of edits can be impacted by multiple files in the workspace. If you want to replicate your teammate’s environment, it just takes a lot of time to get everything set up. + +Live Share allows you to share the context of the code, so you get instant, bidirectional collaboration. Each of you can use a tool that you’ve personalized so you’re the most productive dev you can be. You can independently investigate an issue without stepping on each other, no need to hand-off control or deal with latency. Collaborate with shared focus only when you want to. + + + +## Find out more +We are excited to give you an early glimpse into Live Share today. Although we are only sharing it as a demo today, we will be releasing a limited private preview soon. If you want to learn more and keep up with the project, you can sign up by clicking [here](https://aka.ms/vsls-signup). + +Happy Coding! + +Amanda + +[@amandaksilver](https://twitter.com/amandaksilver) #VSLiveShare diff --git a/blogs/2017/11/15/ls-dual-screen.png b/blogs/2017/11/15/ls-dual-screen.png new file mode 100644 index 0000000000000000000000000000000000000000..d8a3ed4e32d6651f3f64ea576df73796a07304b3 --- /dev/null +++ b/blogs/2017/11/15/ls-dual-screen.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:02acc0d4ac582d98574f589bd889037b611aad96abfaba6a1662419c59edab1a +size 291804 diff --git a/blogs/2017/11/15/ls-social-resized.png b/blogs/2017/11/15/ls-social-resized.png new file mode 100644 index 0000000000000000000000000000000000000000..a8a9591d53d16e261c69b992e20fd80fd88438a0 --- /dev/null +++ b/blogs/2017/11/15/ls-social-resized.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f13cfb294222e083150456233b3f361cdbaac3dba3eb09ac594691a0019d2d90 +size 176206 diff --git a/blogs/2017/11/15/ls-social.png b/blogs/2017/11/15/ls-social.png new file mode 100644 index 0000000000000000000000000000000000000000..c53ba24d3f1fa8d1ce41f6fcb2f9f912dbcdf9e9 --- /dev/null +++ b/blogs/2017/11/15/ls-social.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a2fe520ea801513f56c4db31de1b09a77618e4bfd6f83687cd89e651cf1a71fa +size 563824 diff --git a/blogs/2017/11/15/vs-code-ls-session.png b/blogs/2017/11/15/vs-code-ls-session.png new file mode 100644 index 0000000000000000000000000000000000000000..f9b400c304651d7459efe1950f7ba2169f3da0b7 --- /dev/null +++ b/blogs/2017/11/15/vs-code-ls-session.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5b9ce638da4eb04a11249d7780cab8f150914b9148003ac1c7cece8ab0e2fdaf +size 496893 diff --git a/blogs/2017/11/15/vs-code-ls-session2.png b/blogs/2017/11/15/vs-code-ls-session2.png new file mode 100644 index 0000000000000000000000000000000000000000..aa03f9ce1393708a99ad95bbdf3ff94e0e51eba2 --- /dev/null +++ b/blogs/2017/11/15/vs-code-ls-session2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9a3b137026cd6698767187abb0826682986842d0d30c5bcc2503a431da331e2c +size 531144 diff --git a/blogs/2017/11/16/connect-social.png b/blogs/2017/11/16/connect-social.png new file mode 100644 index 0000000000000000000000000000000000000000..956010157c05656fae97eaa40b93d241453326e6 Binary files /dev/null and b/blogs/2017/11/16/connect-social.png differ diff --git a/blogs/2017/11/16/connect.md b/blogs/2017/11/16/connect.md new file mode 100644 index 0000000000000000000000000000000000000000..168fd087e61aef35d0634be0e1230b1945c54a1d --- /dev/null +++ b/blogs/2017/11/16/connect.md @@ -0,0 +1,83 @@ +--- +Order: 35 +TOCTitle: Connect 2017 +PageTitle: Visual Studio Code 2.6M Users, 12 months of momentum and more to come. +MetaDescription: Visual Studio Code 2.6M Users, 12 months of momentum and more to come. +MetaSocialImage: /assets/blogs/2017/11/16/connect-social.png +Date: 2017-11-16 +ShortDescription: Visual Studio Code 2.6M Users, 12 months of momentum and more to come. A summary of news from Connect(); 2017 +Author: Sean McBreen +--- +# Visual Studio Code at Connect(); 2017 + +November 15, 2017 Sean McBreen, [@nz_sean](https://twitter.com/nz_sean) + +On the day of our annual developer conference ([tune in here](https://www.microsoft.com/en-us/connectevent) if you missed it), we thought it would be cool to reflect on a few things highlighted today and touch on some things that have happened for Visual Studio Code in the last 12 months, for example: + +* Over 15,000 of you contributed to VS Code, making us the #1 project in the [2017 GitHub Octoverse](https://octoverse.github.com/). +* More than 2,600,000 people use VS Code every month, up by over 160% in the last year. + +>![1.0 image](metrics.svg) + +We have come a long way and a big reason is the amazing support we have from the community. We'd like to start with a big **THANK YOU!** + +## Announcements and news from Connect(); + +At this year's Connect(); event, you'll see VS Code in the keynote, in general sessions, and in plenty of on-demand content. + +Here are a few highlights: + +* **Visual Studio Live Share** We showed a glimpse of the future with real-time collaborative editing and debugging in both VS Code and VS IDE - no need to clone a repo, copy code or configuration anything. Find out more on the [Visual Studio Live Share page](/visual-studio-live-share). + +* **Java and Python support** - We're getting serious about [Python](/docs/languages/python) and [Java](/docs/languages/java) for VS Code by staffing full time teams. There was a nice demo of this support in the Visual Studio General Session showing debugging of an Azure Java Function and running Python unit tests. + +* **Debugging inside containers** - Containerized development is a great way to replicate your production environment, and work on multiple projects while keeping your development environment clean. With [the Docker extension](https://marketplace.visualstudio.com/items?itemName=PeterJausovec.vscode-docker), you can run `docker-compose` and automatically connect VS Code's debugger to a Node.js app running inside the container. + +* **Work with Azure** - There are now extensions for [many Azure services](https://marketplace.visualstudio.com/search?target=VSCode&category=Azure&sortBy=Downloads), making tasks like deploying web apps, managing container registries and images, and working with databases a lot simpler. + +* **Visual Studio Code 1.18** - This was a big release. We crossed off several of the most requested features, such as: Multi-root workspaces, Git status in the Explorer, vertical panel positioning, auto-imports, several performance improvements, and more. See the [release notes](https://code.visualstudio.com/updates/v1_18) for details. + +There was a lot of VS Code activity at Connect(); but as we look back at the last 12 months, we also feel good about our pace in improving VS Code. + +## The community and VS Code + +Many of the new features have come from the community; through issues, pull requests, and though the creation of Extensions. We have seen a huge amount of progress and again we want to say **THANK YOU!** + +* We processed over [2,300 PRs](https://github.com/Microsoft/vscode/pulls?q=is%3Apr+is%3Aclosed). +* We closed over [30,000 issues](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+is%3Aclosed). +* There are now more than [4,700 published extensions](https://marketplace.visualstudio.com/search?target=VSCode&category=All%20categories&sortBy=Downloads). + +## A sampling of features across the last 12 months + +In each monthly release, we've added features and improvements that we hope you love. Across the last 12 months, there's been a lot of them but here is a small sampling... + +![Roadmap](roadmap.svg) + +Release|Features|Foundation +-------|----------|--------- +[October 2017](/updates/v1_18) | Multi-root workspaces
Vertical panel layout
Inline Git change review
Auto-import JS/TS | Improved Windows Cold start
Decoration optimizations
Improved recommendations +[September 2017](/updates/v1_) | Support for multiple SCM repos
Region folding
Import Suggestions| macOS touch bar support
Terminal performance improvements +[August 2017](/updates/v1_17) | HTML auto-tag close
HTML/CSS color picker
JS/TS Refactoring – Extract Method +[July 2017](/updates/v1_16) | Emmet 2.0 Support
Loaded scripts explorer | 64-bit Windows Support
Large file support +[June 2017](/updates/v1_15) | Terminal find, select & copy
Command Pallette MRU list
Improved auto indentation
Debugging Recipes
| Multi-root workspaces: in preview
Improved screen reader support +[May 2017](/updates/v1_13) | Mini-map on by default (and others)
Improved IntelliSense Documentation
Resolve git conflicts inline|Faster debugging performance +[April 2017](/updates/v1_12) | Workbench theming
Source Control providers
JavaScript Type checking | Improved download speed
macOS Native Tabs +[March 2017](/updates/v1_11) | Panel maximize & restore
Async Call Stack support
Keyboard shortcuts editor | Faster search over files
Source Control API
Increased extension size limit +[February 2017](/updates/v1_10) | Minimap
Drag & drop in editor
Column breakpoints|Official Linux repositories
Language specific settings +[January 2017](/updates/v1_9) | Welcome experience
Interactive playground
Synchronized Markdown preview
Inline variable display in debugging| Single file debugging
Extension Packs +December 2016 | OK - You got us, we took a break over the holiday period 😊 +[November 2016](/updates/v1_8) | Hot Exit
Zen Mode
JavaScript IntelliSense in HTML| New settings editor +[October 2016](/updates/v1_7) | Horizontal Editor layouts
Printable keyboard shortcuts sheets
Conditional breakpoints
Keymaps for Sublime & Atom| + +Phew - that was a long list of updates. + +## Looking forward +We are only getting started, and with [almost 3,000 open feature requests](https://github.com/Microsoft/vscode/issues?q=is%3Aopen+is%3Aissue+label%3Afeature-request+sort%3Areactions-%2B1-desc) we are not running out of ideas soon. So earlier this month we updated our [public roadmap](https://github.com/Microsoft/vscode/wiki/Roadmap), which gives you an idea of where we are focusing next. As always push us along by up-voting requests you care about. + +If you want to know what we have been up to check out our [release notes](https://code.visualstudio.com/updates) if you are ever interested in what we shipped in a given month that's the first place to look. Of course you can track along with us by looking at our [monthly iteration plans](https://github.com/Microsoft/vscode/wiki/Iteration-Plans) and by using our [insiders build](https://code.visualstudio.com/insiders/) where you can get new stuff every day. + +Ok that's it - but don't worry we will be back with more news and updates soon. + +Happy Coding! + +Sean diff --git a/blogs/2017/11/16/metrics.svg b/blogs/2017/11/16/metrics.svg new file mode 100644 index 0000000000000000000000000000000000000000..7c0f15c54e1cd82c848365f5bcfe414eea767374 --- /dev/null +++ b/blogs/2017/11/16/metrics.svg @@ -0,0 +1 @@ +blog-vscode-metrics \ No newline at end of file diff --git a/blogs/2017/11/16/roadmap.svg b/blogs/2017/11/16/roadmap.svg new file mode 100644 index 0000000000000000000000000000000000000000..d40efcd70294a2708884112035fa21a9a4a2833f --- /dev/null +++ b/blogs/2017/11/16/roadmap.svg @@ -0,0 +1 @@ +blog-vscode-roadmap \ No newline at end of file diff --git a/blogs/2017/12/20/break_on_load_after.png b/blogs/2017/12/20/break_on_load_after.png new file mode 100644 index 0000000000000000000000000000000000000000..dd3a27b50870265635e22991bcaddf45d46508e3 --- /dev/null +++ b/blogs/2017/12/20/break_on_load_after.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a7e900d73ed9e8323ea14e12e8db24fa30a81e20f6e97d9f8319ab0c74ce1d93 +size 128230 diff --git a/blogs/2017/12/20/break_on_load_before.png b/blogs/2017/12/20/break_on_load_before.png new file mode 100644 index 0000000000000000000000000000000000000000..6f0b2d1a9b3ecf28b105c4b71c6861ff8b17c86b Binary files /dev/null and b/blogs/2017/12/20/break_on_load_before.png differ diff --git a/blogs/2017/12/20/chrome-debugging.md b/blogs/2017/12/20/chrome-debugging.md new file mode 100644 index 0000000000000000000000000000000000000000..d2c7c57a850477079137f4fe021bbc74155bc867 --- /dev/null +++ b/blogs/2017/12/20/chrome-debugging.md @@ -0,0 +1,88 @@ +--- +Order: 36 +TOCTitle: What's New for Chrome Debugging +PageTitle: What's New for Chrome debugging in VS Code +MetaDescription: What's New for Chrome debugging in Visual Studio Code +MetaSocialImage: /assets/blogs/2017/12/20/social_paused.png +Date: 2017-12-20 +ShortDescription: Learn what's new with Chrome debugging in Visual Studio Code +Author: Kenneth Auchenberg +--- +# What's new for Chrome debugging + +December 20, 2017 by [Kenneth Auchenberg](https://twitter.com/auchenberg) + +Over the recent months, we have been busy improving the Chrome debugging experience for Visual Studio Code, and today we are happy to release three new features that we think will make client-side JavaScript debugging in VS Code easier and more reliable. + +If you aren't familiar with the Microsoft [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) extension, it allows you to debug your client-side JavaScript running in Google Chrome. This adds a new aspect to VS Code's existing JavaScript debugging experience, where out-of-the-box you can debug your server-side JavaScript in Node.js. Having both debuggers installed allows you to do seamless full-stack JavaScript debugging. + +## Use VS Code and Chrome DevTools at the same time! + +The first thing we have been working on with the Google Chrome team is to make it possible to use both VS Code and Chrome DevTools at the same time! + +This has been a user request since day one, but we were limited by Chrome's lack of [support for multi remote debugging connections](https://bugs.chromium.org/p/chromium/issues/detail?id=129539). This meant that when VS Code connected to Chrome, their Chrome DevTools would be kicked out, and when you opened Chrome DevTools, VS Code would be kicked out. + +Multiple connections means that you now can debug your JavaScript from VS Code while using the DOM Explorer, profiler or any other tool inside Chrome DevTools, without getting disconnected! + +![chrome_code](code_chrome_devtools.gif) + +The Chrome team began working on this a few months ago, and we have been working closely with them to make sure the VS Code experience is optimal. Multi-connections [shipped officially in Chrome 63](https://developers.google.com/web/updates/2017/10/devtools-release-notes#multi-client), and works out-of-the-box with VS Code. To get multi-connection support, update to the latest Chrome version, and you should be good to go. + +## Synchronized stepping between Chrome DevTools and VS Code + +We think being able to combine VS Code and Chrome DevTools is an extremely powerful experience. It enables you to pick the right tool for the scenario, without being forced to make the hard choice of replacing one tool with another. VS Code lets you debug JavaScript in your editor, but we also recognize that some users prefer to debug JavaScript from DevTools, so instead of trying to replace DevTools, we instead see this as an opportunity to integrate. + +The first step towards better integrating the tools is **synchronized stepping between Chrome DevTools and VS Code**, as shown here: + +![sync_stepping](sync_stepping.gif) + +Synchronized stepping allows you to debug your JavaScript source code in VS Code and Chrome DevTools at the same time, and gives you the opportunity to seamlessly jump between the two tools. From within each tool, you can step-in, continue, and debug your JavaScript without worrying about the other debugger getting out of sync. + +It's still early days and we are excited to explore the new world of integration that's possible with connected editors and DevTools. + +## Localized debugging UI +In this release we have also enabled localization of core parts of our debugger, which means that features such as `break on uncaught exceptions` and property descriptions in our `launch.json` now are localized and available for our supported languages, such as Chinese. + +![locale1](locale1.png) + +## Breakpoints set before your app runs + +Another feature we have been working on with [our friends in Visual Studio](https://github.com/Microsoft/vscode-chrome-debug-core/pull/241) is the ability for us to set breakpoints in JavaScript before it gets executed in Chrome. This sounds very simple, but is quite complicated when you dive into the details of how JavaScript can be loaded and executed asynchronously. + +Many users have had the experience that their breakpoints aren't hit when launching Chrome. To add to their confusion, their breakpoints are hit after a simple page refresh. Why would that be? It's a bit complicated, but it comes down to a timing issue between VS Code and Chrome, which is best illustrated in a timeline: + +![](break_on_load_before.png) + +As you can see on the timeline in yellow, the issue is that some JavaScript is executed before VS Code sets the breakpoints. + +This means that if you have breakpoints in source code that would get *immediately executed* as a part of a page load, VS Code hasn't been able to set the breakpoints before execution had completed. The workaround is to do a page refresh which re-executes the code and therefore triggers the breakpoint. + +Good news! We have found a way where you reliably can set breakpoints in early executed source code, which we call [`break-on-load breakpoints`](https://github.com/Microsoft/vscode-chrome-debug/issues/445). + +Break-on-load breakpoints are powered by DOM Instrumentation Breakpoints in Chrome that allow us to pause script execution every time a new script is loaded. This changes the workflow for our debugger, and allows us to have more time to set breakpoints before your JavaScript is executed. + +![](break_on_load_after.png) + +### Enable break-on-load + +We are releasing break-on-load breakpoints as an experimental feature for our Chrome Debugger, and you can enable the feature by setting the new `breakOnLoad` property to `true` in your `launch.json` configuration: + +```json +{ + "type": "chrome", + "request": "launch", + "name": "Chrome", + "url": "http://localhost:3000", + "webRoot": "${workspaceRoot}/src", + "breakOnLoad": true +} +``` + +Enabling break-on-load breakpoints will have an impact on your initial page load performance, as the debugger briefly pauses Chrome every time a new script is loaded. For that reason, this is currently an opt-in feature. If you are experiencing missing breakpoints, try enabling break-on-load breakpoints and let us know how they work for you. + + +That's it for now. It's a big update for our Chrome debugger, and we can't wait to hear your feedback on these new features. In a world where your editor is more integrated with DevTools, let us know what you would expect or want from your tools. + +Happy Coding! + +Kenneth ([@auchenberg](https://twitter.com/auchenberg)) \ No newline at end of file diff --git a/blogs/2017/12/20/code_chrome_devtools.gif b/blogs/2017/12/20/code_chrome_devtools.gif new file mode 100644 index 0000000000000000000000000000000000000000..d017936ef8232e0b2f7171c684a8754dd6564165 --- /dev/null +++ b/blogs/2017/12/20/code_chrome_devtools.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:12470313903116e55905a96abc3a3bb317f601ef688404292fbed149d2bfb65a +size 4932810 diff --git a/blogs/2017/12/20/locale1.png b/blogs/2017/12/20/locale1.png new file mode 100644 index 0000000000000000000000000000000000000000..1fb0d2cd66c4e316e67914a26c4a8d54dc0238b8 Binary files /dev/null and b/blogs/2017/12/20/locale1.png differ diff --git a/blogs/2017/12/20/social_paused.png b/blogs/2017/12/20/social_paused.png new file mode 100644 index 0000000000000000000000000000000000000000..6b03e486ba5c0d9749e0b0a9ad652cb2a1756abe --- /dev/null +++ b/blogs/2017/12/20/social_paused.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ff09908e6493eae6def742f78ab2478fa91c1d1d2a1c64db29c90d60a014d547 +size 408988 diff --git a/blogs/2017/12/20/sync_stepping.gif b/blogs/2017/12/20/sync_stepping.gif new file mode 100644 index 0000000000000000000000000000000000000000..b00540341651416da9bf1409ce5a29eadaee2819 --- /dev/null +++ b/blogs/2017/12/20/sync_stepping.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6327a421be31ab50074a0fc6ff5dbd92197c68fd0d6baa254061c846f5e8e21b +size 9731770 diff --git a/blogs/2018/03/23/fileopen.png b/blogs/2018/03/23/fileopen.png new file mode 100644 index 0000000000000000000000000000000000000000..53ab7fa66b38e0d28f0037d793fa109832cc95ba Binary files /dev/null and b/blogs/2018/03/23/fileopen.png differ diff --git a/blogs/2018/03/23/memoryusage.png b/blogs/2018/03/23/memoryusage.png new file mode 100644 index 0000000000000000000000000000000000000000..1908084e9b1378ce3607f37c903e9ccceff6cf8e Binary files /dev/null and b/blogs/2018/03/23/memoryusage.png differ diff --git a/blogs/2018/03/23/piece-tree.gif b/blogs/2018/03/23/piece-tree.gif new file mode 100644 index 0000000000000000000000000000000000000000..0d2881f9d2e009b384c2f3a899d5934fd688d9de --- /dev/null +++ b/blogs/2018/03/23/piece-tree.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:610e3d21a34ef0f8167709a774ad1775b460937ed0d69f33e0335faa7dbbada7 +size 102083 diff --git a/blogs/2018/03/23/read.png b/blogs/2018/03/23/read.png new file mode 100644 index 0000000000000000000000000000000000000000..dc196d435b713f31ae95266ed1227be61d8315d4 Binary files /dev/null and b/blogs/2018/03/23/read.png differ diff --git a/blogs/2018/03/23/scrolling.png b/blogs/2018/03/23/scrolling.png new file mode 100644 index 0000000000000000000000000000000000000000..e0d855e58870aa8c37be09aaaaab746a911d72c2 Binary files /dev/null and b/blogs/2018/03/23/scrolling.png differ diff --git a/blogs/2018/03/23/text-buffer-reimplementation.md b/blogs/2018/03/23/text-buffer-reimplementation.md new file mode 100644 index 0000000000000000000000000000000000000000..6a5edccb6269009834945852cc89b55c6a18af16 --- /dev/null +++ b/blogs/2018/03/23/text-buffer-reimplementation.md @@ -0,0 +1,276 @@ +--- +Order: 37 +TOCTitle: Text Buffer Reimplementation +PageTitle: Text Buffer Reimplementation, a Visual Studio Code Story +MetaDescription: Text Buffer Reimplementation in the Visual Studio Code/Monaco editor +Date: 2018-03-23 +Author: Peng Lyu +MetaSocialImage: +--- +# Text Buffer Reimplementation + +March 23, 2018 by Peng Lyu, [@njukidreborn](https://twitter.com/njukidreborn) + +The Visual Studio Code 1.21 release includes a brand new text buffer implementation which is much more performant, both in terms of speed and memory usage. In this blog post, I'd like to tell the story of how we selected and designed the data structures and algorithms that led to those improvements. + +Performance discussions about JavaScript programs usually involve a discussion about how much should be implemented in native code. For the VS Code text buffer, these discussions started more than a year ago. During an in-depth exploration, we found that a C++ implementation of the text buffer could lead to significant memory savings, but we didn't see the performance enhancements we were hoping for. Converting strings between a custom native representation and V8's strings is costly and in our case, compromised any performance gained from implementing text buffer operations in C++. We will discuss this in more detail at [the end](#why-not-native) of this post. + +Not going native, we had to find ways to improve our JavaScript/TypeScript code. Inspiring blog posts like [this one](http://mrale.ph/blog/2018/02/03/maybe-you-dont-need-rust-to-speed-up-your-js.html) from [Vyacheslav Egorov](http://mrale.ph) show ways to push a JavaScript engine to its limits and squeeze out as much performance as possible. Even without low level engine tricks, it is still possible to improve speed by one or more orders of magnitude by using better suited data structures and faster algorithms. + +## Previous text buffer data structure + +The mental model for an editor is line based. Developers read and write source code line by line, compilers provide line/column based diagnostics, stack traces contain line numbers, tokenization engines run line by line, etc. Although simple, the text buffer implementation powering VS Code hadn't changed much since the first day we kicked off the Monaco project. We used an array of lines, and it worked pretty well because typical text documents are relatively small. When the user is typing, we located the line to modify in the array and replaced it. When inserting a new line, we spliced a new line object into the line array and the JavaScript engine would do the heavy lifting for us. + +However, we kept receiving reports that opening certain files would cause Out-Of-Memory crashes in VS Code. For example, one user failed to open a [35 MB file](https://github.com/Microsoft/vscode/issues/13187). The root cause was that the file had too many lines, 13.7 million. We would create a `ModelLine` object for each line and every object used around 40-60 bytes, so the line array used around 600MB memory to store the document. That's roughly 20 times the initial file size! + +Another problem with the line array representation was the speed of opening a file. To construct the array of lines, we had to split the content by line breaks, such that we would get a string object per line. The split itself hurts performance which you'll see in benchmarks further down. + +## Finding a new text buffer implementation + +The old line array representation can take a lot of time to create and consumes a lot of memory, but it gives fast line look-up. In a perfect world, we would store only the text of the file and no additional metadata. Thus, we started looking for data structures that require less metadata. After reviewing various data structures, I found that [piece table](https://en.wikipedia.org/wiki/Piece_table) may be a good candidate to start with. + +### Avoiding too much meta-data by using a piece table + +Piece table is a data structure used to represent a series of edits on a text document (source code in TypeScript): + +```ts +class PieceTable { + original: string; // original contents + added: string; // user added contents + nodes: Node[]; +} + +class Node { + type: NodeType; + start: number; + length: number; +} + +enum NodeType { + Original, + Added +} +``` + +After the file is initially loaded, the piece table contains the whole file contents in the `original` field. The `added` field is empty. There is a single node of type `NodeType.Original`. When a user types at the end of a file, we append the new content to the `added` field, and we will insert a new node of type `NodeType.Added` at the end of the node list. Similarly, when a user makes edits in the middle of a node, we will split that node and insert a new one as needed. + +The animation below shows how to access the document line by line in a piece table structure. It has two buffers (`original` and `added`) and three nodes (which is caused by an insertion in the middle of the `original` content`). + +--- + +![Traditional piece table](traditional-piece-table.gif) + +--- + +The initial memory usage of a piece table is close to the size of the document and the memory needed for modifications is proportional to the number of edits and text added. So typically a piece table makes good use of memory. However, the price for low memory usage is that accessing a logical line is slow. For example, if you want to get the content of the 1000th line, the only way is to iterate over every character starting at the beginning of the document, find the first 999 line breaks, and read each character until the next line break. + +### Use caching for faster line lookup + +The traditional piece table nodes only contain offsets, but we can add line break information to make line content lookup faster. The intuitive way to store line break positions is to store the offsets for each line break encountered in a node's text: + +```ts +class PieceTable { + original: string; + added: string; + nodes: Node[]; +} + +class Node { + type: NodeType; + start: number; + length: number; + lineStarts: number[]; +} + +enum NodeType { + Original, + Added +} +``` + +For example, if you want to access the second line in a given `Node` instance, you can read `node.lineStarts[0]` and `node.lineStarts[1]` which will give the relative offsets at which a line begins and ends. Since we know how many line breaks a node has, accessing a random line in the document is straight forward: read each node starting from the first one until we find the target line break. + +The algorithm remains simple, and it works better than before as we can now jump over entire chunks of text rather than iterate character-by-character. We'll see later on that we can do even better than that. + +### Avoid the string concatenation trap + +The piece table holds two buffers, one for original content loaded from disk, and another for user edits. In VS Code, we are loading text files using Node.js `fs.readFile` that delivers content in 64KB chunks. So when the file is large, for example 64 MB, we'll receive 1000 chunks. After having received all of the chunks, we can concatenate them into one large string and store it in the `original` field of the piece table. + +This sounds reasonable until V8 steps on your toes. I tried to open a 500MB file and got an exception because in the version of V8 I used, the maximum string length is 256MB. This limit will be lifted to 1GB in future versions of V8 but that doesn't really solve the problem. + +Instead of holding an `original` and an `added` buffer, we can hold a list of buffers. We can try to keep that list short or we can be inspired by what we get back from `fs.readFile` and avoid any string concatenation. Each time we receive a 64KB chunk from disk, we push it directly to the `buffers` array and create a node that points to this buffer: + +```ts +class PieceTable { + buffers: string[]; + nodes: Node[]; +} + +class Node { + bufferIndex: number; + start: number; // start offset in buffers[bufferIndex] + length: number; + lineStarts: number[]; +} +``` + +### Boost line lookup by using a balanced binary tree + +With string concatenation out of the way, we can now open large files but this leads us to another potential performance issue. Say we load a 64MB file, the piece table will have 1000 nodes. Even though we cache line break positions in every node, we don't know which absolute line number is in which node. To get the content of a line, we have to go through all nodes until we find the node containing that line. In our example, we have to iterate through up to 1000 nodes depending on which line number we look for. Thus, the time complexity of the worst case is O(N) (N is the count of nodes). + +Caching the absolute line numbers in each node and using binary search on the list of nodes boosts lookup speed but whenever we modify a node, we have to visit all following nodes to apply the line number delta. This is a no-go but the idea of binary search is good. To achieve the same effect, we can leverage a balanced binary tree. + +We now have to decide what metadata we should use as the key to compare tree nodes. As said, using the node's offset in the document or the absolute line number will bring the time complexity of editing operations to O(N). If we want a time complexity of O(log n), we need something that's only related to a tree node's subtree. Thus, when a user edits text, we recompute the metadata for the modified nodes, and then bubble the metadata change along the parent nodes all the way to the root. + +If a `Node` has only four properties (`bufferIndex`, `start`, `length`, `lineStarts`), it takes seconds to find the result. To get faster, we can also store the text length and the line break count of a node's left subtree. This way searching by offset or line number from the root of the tree can be efficient. Storing metadata of the right subtree is the same but we don't need to cache both. + +The classes now look like this: + +```ts +class PieceTable { + buffers: string[]; + rootNode: Node; +} + +class Node { + bufferIndex: number; + start: number; + length: number; + lineStarts: number[]; + + left_subtree_length: number; + left_subtree_lfcnt: number; + left: Node; + right: Node; + parent: Node; +} +``` + +Among all the different types of balanced binary trees, we choose [red-black tree](https://en.wikipedia.org/wiki/Red–black_tree) because it is more 'editing' friendly. + +### Reduce objects allocation + +Assume we store the line break offsets in each node. Whenever we change the node, we might have to update the line break offsets. For example, say we have a node that contains 999 line breaks, the `lineStarts` array has 1000 elements. If we split the node evenly, then we'll create two nodes, each has an array containing around 500 elements. As we are not directly operating on linear memory space, splitting an array into two is more costly than just moving pointers. + +The good news is that the buffers in a piece table are either readonly (original buffers) or append-only (changed buffers), so the line breaks within a buffer don't move. `Node` can simply hold two references to the line break offsets on its corresponding buffer. The less we do, the better the performance is. Our benchmarks showed that applying this change made the text buffer operations in our implementation three times faster. But more about the actual implementation later. + +```ts +class Buffer { + value: string; + lineStarts: number[]; +} + +class BufferPosition { + index: number; // index in Buffer.lineStarts + remainder: number; +} + +class PieceTable { + buffers: Buffer[]; + rootNode: Node; +} + +class Node { + bufferIndex: number; + start: BufferPosition; + end: BufferPosition; + ... +} +``` + +--- + +![piece tree](piece-tree.gif) + +--- + +## Piece tree + +I'd love to call this text buffer **"Multiple buffer piece table with red-black tree, optimized for line model"**. But in our daily standup, when everyone is limited to 90 seconds to share what they've been up to, repeating this long name multiple times would not be wise. So I simply started calling it **"piece tree"**, which reflects what it is. + +Having a theoretical understanding of this data structure is one thing, real world performance is another. The language you use, the environment the code runs in, the way clients invoke your API, and other factors may significantly affect the outcome. Benchmarks can provide a comprehensive picture so we ran benchmarks on small/medium/large files against the original line array implementation and the piece tree implementation. + +### Preparations + +For telling results, I looked for realistic files online: + +* [checker.ts](https://github.com/Microsoft/TypeScript/blob/master/src/compiler/checker.ts) - 1.46 MB, 26k lines. +* [sqlite.c](https://github.com/kripken/emscripten/blob/master/tests/sqlite/sqlite3.c) - 4.31MB, 128k lines. +* [Russian English Bilingual dictionary](https://github.com/titoBouzout/Dictionaries/blob/master/Russian-English%20Bilingual.dic) - 14MB, 552k lines. + +and manually created a couple of large files: + +* Chromium heap snapshot of newly opened VS Code Insider - 54MB, 3M lines. +* checker.ts X 128 - 184MB, 3M lines. + +### 1. Memory usage + +The memory usage of the piece tree immediately after loading is very close to the original file size, and it is significantly lower than the old implementation. First round, piece tree wins: + +![Memory usage](memoryusage.png) + +### 2. File opening times + +Finding and caching line breaks is much faster than splitting the file into an array of strings: + +![File opening](fileopen.png) + +### 3. Editing + +I have simulated two workflows: + +* Making edits in random positions in the document. +* Typing in sequence. + +I tried to mimic these two scenarios: Apply 1000 random edits or 1000 sequential inserts to the document, then see how much time every text buffer needs: + +![Random edits](write.png) + +As expected, line array wins when the file is very small. Accessing a random position in a small array and tweaking a string which has around 100~150 characters is really fast. The line array starts to choke when the file has many lines (100k+). Sequential inserts in large files make this situation worse as the JavaScript engine does a lot of work in order to resize the large array. Piece tree behaves in a stable fashion as each edit is just a string append and a couple red-black tree operations. + +### 4. Reading + +For our text buffers, the hottest method is `getLineContent`. It is invoked by the view code, by the tokenizer, the link detector, and pretty much every component relying on document content. Some of the code traverses the entire file, like the link detector, while other code reads only a window of sequential lines, like the view code. So I set out to benchmark this method in various scenarios: + +* Call `getLineContent` for all lines after doing 1000 random edits. +* Call `getLineContent` for all lines after doing 1000 sequential inserts. +* Read 10 distinct line windows after doing 1000 random edits. +* Read 10 distinct line windows after doing 1000 sequential inserts. + +![Read all lines after random edits](read.png) + +TA DA, we found the Achilles heel of piece tree. A large file, with 1000s of edits, will lead to thousands or tens of thousands of nodes. Even though looking up a line is `O(log N)`, where `N` is the number of nodes, that is significantly more than `O(1)` which the line array enjoyed. + +Having thousands of edits is relatively rare. You might get there after replacing a commonly occurring sequence of characters in a large file. Also, we are talking about microseconds for each `getLineContent` call so it is not something we are concerned about at this time. Most of `getLineContent` calls are from view rendering and tokenization, and the post processes of line contents are much more time consuming. DOM construction and rendering or tokenization of a view port usually takes tens of milliseconds, in which `getLineContent` only accounts for less than 1%. Nevertheless, we are considering eventually implementing a normalization step, where we would recreate buffers and nodes if certain conditions such as a high number of nodes are met. + +## Conclusion and gotchas + +Piece tree outperforms line array in most scenarios, with the exception of line based lookup, which was to be expected. + +### Lessons learned + +* The most important lesson this reimplementation taught me is to **always do real world profiling**. Every time I found that my assumptions about which methods would be hot did not match reality. For example, when I started the piece tree implementation, I focused on tuning the three atomic operations: `insert`, `delete` and `search`. But when I integrated it in VS Code, none of those optimizations mattered. The hottest method was `getLineContent`. +* **Dealing with `CRLF` or mixed line breaks sequences is a programmer's nightmare**. For every modification, we need to check if it splits a Carriage Return/Line Feed (CRLF) sequence, or if it creates a new CRLF sequence. Dealing with all the possible cases, in the context of a tree, took several attempts until I had a solution that was correct and fast. +* **GC can easily eat your CPU time**. Our text model used to assume that the buffer is stored in an array and we frequently use `getLineContent` even though sometimes it wasn't necessary. For example, if we just want to know the character code of the first character of a line, we used a `getLineContent` first and then did `charCodeAt`. With piece tree, `getLineContent` creates a substring and after checking the character code, the line substring is thrown away immediately. This is wasteful and we are working on adopting better suited methods. + +### Why not native? + +I promised at the beginning that I would get back to this question. + +**TL;DR**: We tried. It didn't work out for us. + +We built a text buffer implementation in C++ and used native node module bindings to integrate it in VS Code. The text buffer is a popular component in VS Code and thus many calls were being made to the text buffer. When both the caller and the implementation were written in JavaScript, V8 was able to inline many of these calls. With a native text buffer, there are **JavaScript <=> C++** round trips and given the number to round-trips, they slowed everything down. + +For example, the VS Code **Toggle Line Comment** command is implemented by looping through all the selected lines, and analyzing them one-by-one. This logic is written in JavaScript, and will invoke `TextBuffer.getLineContent` for each line. For each call, we end up crossing the C++/JavaScript boundary and we have to return a JavaScript `string` in order to respect the API that all of our code is built on top of. + +Our options are simple. In C++, we either allocate a new JavaScript `string` on each call to `getLineContent` which implies copying the actual string bytes around, or we leverage V8's `SlicedString` or `ConstString` types. However, we can use V8's string types only if our underlying storage is also using V8's strings. Unfortunately, V8's strings are not multi-thread safe. + +We could have tried to overcome this by changing the TextBuffer API, or by moving more and more code to C++ to avoid the JavaScript/C++ boundary cost. However, we realized we were doing two things at the same time: we were writing a text buffer using a different data structure than a line array, and we were writing it in C++ rather than JavaScript. So, rather than spending half a year on something we didn't know would pay off, we decided to keep the text buffer's runtime in JavaScript, and only change the data structure and associated algorithms. In our opinion, this was the right decision. + +## Future work + +We still have a handful of cases that need to be optimized. For example, the **Find** command currently runs line-by-line but shouldn't. We can also avoid needless calls to `getLineContent` when only a line substring is needed. We will incrementally release these optimizations. Even without these further optimizations, the new text buffer implementation provides a better user experience then what we had before and is now the default in the latest stable VS Code version. + +Happy Coding! + +Peng Lyu, VS Code Team member [@njukidreborn](https://twitter.com/njukidreborn) \ No newline at end of file diff --git a/blogs/2018/03/23/traditional-piece-table.gif b/blogs/2018/03/23/traditional-piece-table.gif new file mode 100644 index 0000000000000000000000000000000000000000..965d4a76e47c877f815f8a28827ab30607191c15 Binary files /dev/null and b/blogs/2018/03/23/traditional-piece-table.gif differ diff --git a/blogs/2018/03/23/write.png b/blogs/2018/03/23/write.png new file mode 100644 index 0000000000000000000000000000000000000000..455cbd8e36db055033a355aeef6290f9fd9d3133 --- /dev/null +++ b/blogs/2018/03/23/write.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:34a291085f75f117362b32c01a354e11bd44c25e522cafa1590264b9474b35bb +size 144891 diff --git a/blogs/2018/04/25/Beautify.gif b/blogs/2018/04/25/Beautify.gif new file mode 100644 index 0000000000000000000000000000000000000000..7a46ebf40475f957c6eddcbe931a911740511d18 --- /dev/null +++ b/blogs/2018/04/25/Beautify.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:997c9d61325479e97325556b141c6e80cf983dfa27d4c9d76eaf75cc17afd4ee +size 7911346 diff --git a/blogs/2018/04/25/BingDiagram.png b/blogs/2018/04/25/BingDiagram.png new file mode 100644 index 0000000000000000000000000000000000000000..dea96b9f04c0095cf0ec82d9c37c555bbbc88ab0 --- /dev/null +++ b/blogs/2018/04/25/BingDiagram.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:db1c9e5df728fa8812910ee5d1460785df2fbd74a8537eadda3bd946d62b1849 +size 171005 diff --git a/blogs/2018/04/25/FormatOnKeypress.gif b/blogs/2018/04/25/FormatOnKeypress.gif new file mode 100644 index 0000000000000000000000000000000000000000..eb4b1f3311a644aa1a4d7e029d0ffa0a68ffdca5 --- /dev/null +++ b/blogs/2018/04/25/FormatOnKeypress.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a19f72482ae6173862c1a3fa2044be095be8cc636281c9265ccc818f90231642 +size 5928834 diff --git a/blogs/2018/04/25/OpenFilesOnLeft.gif b/blogs/2018/04/25/OpenFilesOnLeft.gif new file mode 100644 index 0000000000000000000000000000000000000000..e5928d67fac9eaaced26cd0a4ea261c457956ca1 --- /dev/null +++ b/blogs/2018/04/25/OpenFilesOnLeft.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:afdeabbf1f85b7ef6ebfe239a8484105cbe6d6c2cb9eec4f2e95a8d5cd2bba05 +size 8431694 diff --git a/blogs/2018/04/25/SocialImg.gif b/blogs/2018/04/25/SocialImg.gif new file mode 100644 index 0000000000000000000000000000000000000000..4fcab860811575ae9bfabd775294a5081a13c5e9 --- /dev/null +++ b/blogs/2018/04/25/SocialImg.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6a5d4bd38283b79bc503dc042c23927187a31c26de8881df0d866aa7e261e69a +size 2818380 diff --git a/blogs/2018/04/25/ZoomScrollWheel-before.png b/blogs/2018/04/25/ZoomScrollWheel-before.png new file mode 100644 index 0000000000000000000000000000000000000000..a27d1d37aa62b7cde49412ca26faef6c887f8173 Binary files /dev/null and b/blogs/2018/04/25/ZoomScrollWheel-before.png differ diff --git a/blogs/2018/04/25/ZoomScrollWheel.gif b/blogs/2018/04/25/ZoomScrollWheel.gif new file mode 100644 index 0000000000000000000000000000000000000000..9be6a69e06d90601ac015f8d4d20e81aa1f4d4cc --- /dev/null +++ b/blogs/2018/04/25/ZoomScrollWheel.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8a3223e8e9e4ad730431b3368e92dca095851123ed735f3900a8cd5101401ab3 +size 1669715 diff --git a/blogs/2018/04/25/bing-settings-search.md b/blogs/2018/04/25/bing-settings-search.md new file mode 100644 index 0000000000000000000000000000000000000000..6d7782ab6b3c9bea34c020a061644f4668f522d7 --- /dev/null +++ b/blogs/2018/04/25/bing-settings-search.md @@ -0,0 +1,125 @@ +--- +Order: 38 +TOCTitle: Settings Search +PageTitle: Bing-powered settings search in VS Code +MetaDescription: Improving settings search in VS Code with Bing +MetaSocialImage: /assets/blogs/2018/04/25/SocialImg.gif +Date: 2018-04-25 +ShortDescription: Improving settings search in VS Code with Bing +Author: Rob Lourens +--- +# Bing-powered settings search in VS Code + +April 25, 2018 by Rob Lourens [@roblourens](https://twitter.com/roblourens) and Ankith Karat [ankar@microsoft.com](mailto:ankar@microsoft.com) + +Have you ever had trouble finding a certain setting in VS Code? You're not alone. Looking across common GitHub issues, StackOverflow questions, tweets, and user studies that we've done, we've seen many users having issues finding settings. This is no surprise given that VS Code includes more than 400 settings out of the box, and with extensions installed, many users can have significantly more. If you include typical user mistakes such as typos and the challenge of picking the right search terms, users have a hard time. + +So several months ago, we started talking to the Bing team about whether they could apply their search expertise to our problem. And two months ago, we shipped the result - an intelligent settings search experience powered by Bing. + +
+
+

Before

+ Before example +
+
+

After

+ After example +
+
+ +## How it works + +After a period of discussion and prototyping, we decided on an arrangement in which the Bing team would run a settings search service that would provide intelligent fuzzy settings matches for queries that users search for in VS Code's settings editor. + +Integrating Bing's natural language search capabilities into VS Code proved challenging. To search documents on the web, Bing considers thousands of signals relating to page similarity, click data, user behavior data, etc. But we didn't have this sort of rich metadata available for our settings - just a brief name and description for each one. So the Bing team combined custom services and Bing's fundamental search capabilities to create a system tuned to our search scenario. + +Here is a high level overview of the system: + +![Bing Diagram](BingDiagram.png) + +Let's take a look at each part. + +There are essentially two sides to this system - collecting and indexing setting details offline, and serving up results online. The first part of that is implemented by the Ingestion Service. It's responsible for creating a rich index containing settings from VS Code itself and from extensions. Since we want query response time to be as short as possible, we do as much work as possible up front while ingesting settings to reduce the work we have to do while handling the query. + +### Bing Ingestion Service + +**Collecting VS Code and Extension Settings Data** + +During each build, VS Code starts up in a mode where it writes all of its configuration to a JSON file. We have to actually start VS Code, because we can't determine all the configuration metadata statically. The file includes a few pieces of information per setting - the name, description, type, default value, and for "enum"-type settings, the list of valid values and their descriptions. We then upload the file to Azure Storage. If you're curious, you can see a recent example here: + +[https://ticino.blob.core.windows.net/configuration/123000832/c1cd4378.../configuration.json](https://ticino.blob.core.windows.net/configuration/123000832/c1cd4378c5e5dc434ed959e13556d05240a8ca18/configuration.json) + +`123000832` is a unique build number, computed from the product version plus the number of Git commits since the previous release. `c1cd4378...` is the Git commit id that the build was built off of. And `ticino`, some of you diehard fans might remember, was our original short-lived code name. + +Bing's Polling Service watches the Azure Storage container, notices a new build, and notifies the Ingestion Service. At the same time, Bing is constantly crawling the VS Code extension marketplace, waiting for extension updates and new extensions. When it finds one, it downloads its `package.json` file (for extensions, all configuration metadata is contained in the `package.json`. No need to start it up.) and passes those settings to the Ingestion Service as well. + +This entire process is fully automated and constantly updates the indexed settings in real-time for each of our stable release builds and our daily Insiders builds. Within minutes of the completion of a build, Bing's index has been updated to include any newly added settings. + +**1. Alternative Words Pipeline** + +Users sometimes search with words that are different but equivalent to the words we use in setting names and descriptions. To ensure that we can handle those cases, we integrated Bing's "Alternative Word" generation pipeline. This pipeline collects words with similar meanings to each other from Bing's search data using signals such as user behavior, clicks, online ranking, and page similarity. For example, "update" and "upgrade" are set as "alternative words", and a search for one will return settings that include the other. + +**2. Stemmer and Speller Pipeline** + +We don't want to penalize the user for misspelling the name of a setting, but we found early on that simple fuzzy matching would either miss variations of an English word that a human could understand, or would include too many false positive matches. So we also included a Speller and a Stemmer service, extracted from the full-fledged services that are used on Bing.com, which enrich the index with common misspellings and alternate forms of the same word stem. For example, "formatted", "formatter", "format" - all will be indexed for a setting that uses the word "formatting". + +**3. Natural Language Processing (NLP) Pipeline** + +We also want to enable users to describe their query in their own natural language, so we added Bing's Natural Language Processing pipeline. The pipeline collects commonly used speech and text patterns and adds them to the indexes. For example, it enables the system to identify the important words in "how to disable css validation" to find `"css.validate"`. + +**4. Feedback/Ranking Pipeline** + +We created a feedback mechanism that lets us learn and improve from user feedback. It allows us to manually specify new word pairs or to boost expected results for certain queries. The feedback is uploaded to the service and is reflected by the search results almost immediately. + +**Gating Module** + +Every ingestion into the index goes through the gating module which just ensures that the index hasn't, due to some programming error, become corrupted. We have test cases written that verify the following: + +- The new index is backwards compatible and serves all VS Code builds +- Our Golden query set returns the expected results + +Failure in the gating module will prevent an index ingestion and notifies the team immediately. A dashboard service was also created that allows us to monitor the health of all stages of the pipeline. It has alerting mechanisms and the ability to roll back to the last known good state, to ensure that any issue can be resolved quickly with minimum downtime. + +### Search Service + +Finally, at runtime, the query from our users hits the [Azure Load Balancer](https://docs.microsoft.com/en-us/azure/load-balancer/load-balancer-overview) service that selects one of our geo-replicated servers to handle the query, based on its physical proximity or current load. The Search Service hosted at that location retrieves the relevant results with a lookup in the index, applies manual ranking overrides in some cases, and returns them to the VS Code client. + +## Putting it all together + +We now have a system which does a better job of understanding settings queries and delivers results for many queries that would have returned nothing before. + +Here are some examples: + +![format on keypress](FormatOnKeypress.gif) + +![example - how to open new files on the left](OpenFilesOnLeft.gif) + +![beautify](Beautify.gif) + +If you have a similar problem and don't have a search team to build you a custom service as the Bing team did for us, we still have some good news. You can get started with [Bing's Cognitive Services](https://azure.microsoft.com/en-us/services/cognitive-services/bing-web-search-api/), which will help you add some intelligence into your own apps. For example: +- [Bing Spell Check API](https://azure.microsoft.com/en-us/services/cognitive-services/spell-check/) +- [Language Understanding (LUIS)](https://azure.microsoft.com/en-us/services/cognitive-services/language-understanding-intelligent-service/) +- [Bing Web Search API](https://azure.microsoft.com/en-us/services/cognitive-services/bing-web-search-api/) +- [Bing Custom Search API](https://azure.microsoft.com/en-us/services/cognitive-services/bing-custom-search/) + +## A note about testing + +While developing this system, we needed a way to quantitatively evaluate the results. We decided to build a test framework based on the concept of [Normalized Discounted Cumulative Gain, or NDCG](https://en.wikipedia.org/wiki/Discounted_cumulative_gain). Without getting too far into the weeds, this is a way to grade the results from a search engine, given a query, a set of results, and scores for those results. We wrote quite a few test cases by hand, but realized that we needed an automated way to generate test cases for all settings, including new settings as they would be added, and settings in extensions. So we wrote a tool that can generate test cases automatically for any setting. It uses words from the setting name and description, and runs them through different transformers that simulate users choosing alternate words, making typos, or searching using natural language patterns. We also generated test cases for settings from some popular extensions. + +We run the full test suite every 6 hours, and it can update itself automatically so that it's always testing settings from the latest build. The test suite assures us that the system is running properly, and gives us confidence that when we make changes on the backend, we are not hurting the result quality. + +## What's next + +There are several ways that we can continue to improve the system. For example, we are also setting up an automated feedback loop based on user behavior. If many people search for similar queries, then pick the same result, we know that result is probably a good one and should be ranked higher. + +Currently the service is only indexing in English, but we'd like to index the translated setting descriptions and support searching in non-English languages. There is also some configuration metadata that isn't currently indexed, like possible values for the `"workbench.colorCustomizations"` setting. And taking search a little further, we would like to show results for extensions that aren't currently installed. If you search `"debug python"`, and don't have strong matches for local settings, then we would like to lead you towards an extension that can help you debug Python code. We have also thought about other applications for this technology within VS Code. Maybe the command palette could benefit from a similar service. + +## We need your feedback + +It is now easier to find settings thanks to our friends on the Bing team! User feedback is the best way for us to improve the results, so as you search for settings, please file issues on GitHub if you don't see the results that you expect. In fact, if you're using [VS Code Insiders](https://code.visualstudio.com/insiders/) you will even see a button that will invoke our new issue reporter to make it easier for you to file an issue that includes all the details we need. + +Happy Coding! + +Rob Lourens, VS Code - [@roblourens](https://twitter.com/roblourens) + +Ankith Karat, Bing - [ankar@microsoft.com](mailto:ankar@microsoft.com) diff --git a/blogs/2018/05/07/live-share-public-preview.md b/blogs/2018/05/07/live-share-public-preview.md new file mode 100644 index 0000000000000000000000000000000000000000..c69ae7ca4d9e6b54ed5ab668f09d4ebf25116469 --- /dev/null +++ b/blogs/2018/05/07/live-share-public-preview.md @@ -0,0 +1,52 @@ +--- +Order: 39 +TOCTitle: Live Share Preview +PageTitle: Announcing the Visual Studio Live Share Public Preview +MetaDescription: Real-time collaborative development +MetaSocialImage: /assets/blogs/2017/11/15/ls-social-resized.png +Date: 2018-05-07 +ShortDescription: Real-time collaborative development +Author: Amanda Silver +--- +# Visual Studio Live Share Public Preview + +May 7, 2018 Amanda Silver, [@amandaksilver](https://twitter.com/amandaksilver) + +We are excited to announce the public preview of Visual Studio Live Share! At [Connect last November](https://code.visualstudio.com/blogs/2017/11/15/live-share), we showed how Live Share enables real-time collaborative editing and debugging from the comfort of your favorite tools. Since then, we’ve worked with thousands of developers worldwide, resolved hundreds of issues, and addressed top feature requests such as [adding support for Linux](https://github.com/MicrosoftDocs/live-share/issues/24). We’ve benefited greatly from all the feedback thus far, thank you! Today, we’re excited to announce that every developer using Visual Studio and Visual Studio Code can [get started with Live Share today](https://aka.ms/vsls)! + +## Universal Collaboration + +When talking with developers, the need for better collaboration tools is clear, and isn't limited to any particular programming language or app type. To empower the diverse and increasingly polyglot developer community, we’ve brought Live Share to all the languages and platforms. + +![Python-based IntelliSense](lsp.png) + +Whether you’re building a Python web app, a Go microservice, a React Native mobile app or an Ethereum smart contract, you can use Live Share. Everything from Go to Definition, code fixes/refactorings ("lightbulbs"), build errors, and debugging sessions are shared with guests, which ensures that everyone stays productive no matter what you’re working on. Even better, all of this works without requiring guests to have any language extensions, dependencies, or SDKs installed! You can instantly invite others to work with you and allow them to share the context from your development environment. + +## Shared Terminals + +Modern development commonly makes use of command-line tools to perform tasks such as build and running unit tests. Because the command-line represents such a core component of the common developer workflow, it’s critical that participants within a Live Share session can use them, without requiring a separate tool. To further support your collaborative debugging sessions, and address one of our [top feature requests](https://github.com/MicrosoftDocs/live-share/issues/41), Live Share now allows hosts to share terminals with their guests. + +![Shared terminal](shared-terminal.png) + +When you share a new terminal, it is read-only by default. This allows everyone to see the real-time results of any command you run without needing to expose access to your machine. Additionally, you can choose to make a shared terminal writable, which enables a fully collaborative experience between you and your guests which executes in your environment. This makes pair programming much easier, especially when seeking help with environment configuration. + +## Secure Sharing + +We want collaboration to become simpler and more natural for everyone so that ad-hoc interactions can occur more frequently. However, developers also need to be confident that when they share their source code, they have the necessary control and visibility into who has access, and what files they can see. To improve this balance between simplicity and security, Live Share provides two capabilities: + +1. You can require each guest to be explicitly approved by you before joining your collaboration session. This way, simply gaining access to the share URL (which is already unique for each session) isn't enough to join. + + ![User acceptance dialog](user-accept.png) + +2. You can exclude specific files from your sharing session, so guests can only view what you want them to. No surprises. By default, your .gitignore file is used to determine which files to exclude, but you can customize that behavior using a .vsls.json configuration file. + + ![VSLS configuration file](vsls.json.png) + +These enhancements represent some of our most [frequently requested](https://github.com/MicrosoftDocs/live-share/issues/52) items so you can collaborate with confidence, without adding unnecessary friction. For more information on how to share your projects securely, refer to the [documentation](https://docs.microsoft.com/en-us/visualstudio/liveshare/reference/security). + +## We need your feedback! + +We are excited for you to give [Visual Studio Live Share a try](https://aka.ms/vsls)! Please give us feedback how we might improve the experience for real-time collaborative development even further. If you'd like to learn more, you can refer to the Visual Studio Live Share [documentation](http://aka.ms/vsls-docs). Additionally, if you have any questions, encounter any issues, or have feature requests, please don’t hesitate to [let us know](https://github.com/microsoft/live-share). + +Happy Collaborating!
+Amanda, [@amandaksilver](https://twitter.com/amandaksilver) diff --git a/blogs/2018/05/07/lsp.png b/blogs/2018/05/07/lsp.png new file mode 100644 index 0000000000000000000000000000000000000000..189c993cd8f9fc296153f2b97803a20bfc81efc3 --- /dev/null +++ b/blogs/2018/05/07/lsp.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f22a1bdb8b247b1a5682c93d1cd6fdb07d97036a2ab5153df4401756133e2fa5 +size 237105 diff --git a/blogs/2018/05/07/shared-terminal.png b/blogs/2018/05/07/shared-terminal.png new file mode 100644 index 0000000000000000000000000000000000000000..c583ed4125b880248d80aaecca52dc3a73ab0bcf --- /dev/null +++ b/blogs/2018/05/07/shared-terminal.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dcf67a1165658fba5a5b67e6bb46729665de8c28b5f03f70caf385b59916a162 +size 806459 diff --git a/blogs/2018/05/07/user-accept.png b/blogs/2018/05/07/user-accept.png new file mode 100644 index 0000000000000000000000000000000000000000..a8d53fdd48dd8c80bde4f3600b2746e22c6d4fdc Binary files /dev/null and b/blogs/2018/05/07/user-accept.png differ diff --git a/blogs/2018/05/07/vsls.json.png b/blogs/2018/05/07/vsls.json.png new file mode 100644 index 0000000000000000000000000000000000000000..e466c2587c6a831e5e4a29e3d6dc7c791f5b379d Binary files /dev/null and b/blogs/2018/05/07/vsls.json.png differ diff --git a/blogs/2018/07/12/auto-attach.gif b/blogs/2018/07/12/auto-attach.gif new file mode 100644 index 0000000000000000000000000000000000000000..0949a3d9a759dd40a7ce1ecacd7697b99a48984a --- /dev/null +++ b/blogs/2018/07/12/auto-attach.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6b87482ad595de9ef24c716aae61ab49ef8be781489d6d5336c631394e3020f5 +size 1241094 diff --git a/blogs/2018/07/12/debug-extension-api.png b/blogs/2018/07/12/debug-extension-api.png new file mode 100644 index 0000000000000000000000000000000000000000..d4f4bedf265bb715a33bff9a982b53d6af4e7464 --- /dev/null +++ b/blogs/2018/07/12/debug-extension-api.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8e473bc6fa3aef160833a5eafc88abbd65d0612463cc1bff94a6ba4b6188e66b +size 119146 diff --git a/blogs/2018/07/12/debugger.png b/blogs/2018/07/12/debugger.png new file mode 100644 index 0000000000000000000000000000000000000000..b5c33bfc438793c6cb96d84d4a71b2949fb920ef --- /dev/null +++ b/blogs/2018/07/12/debugger.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:02d5750457436e5c26be781b2ff0c55e648311708a16aaa1b99d1110a362a71d +size 850844 diff --git a/blogs/2018/07/12/debugging_architecture.png b/blogs/2018/07/12/debugging_architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..aff55dc4c43b8f61b236c57c039e00bd1fdb2763 --- /dev/null +++ b/blogs/2018/07/12/debugging_architecture.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4dca69fbe7d3ac5ca9238480ddadbc49391c26a5b7ce7852b16c341954341370 +size 167102 diff --git a/blogs/2018/07/12/introducing-logpoints-and-auto-attach.md b/blogs/2018/07/12/introducing-logpoints-and-auto-attach.md new file mode 100644 index 0000000000000000000000000000000000000000..b33f3cb963b10edde56c38c71339f93ec82d9dc4 --- /dev/null +++ b/blogs/2018/07/12/introducing-logpoints-and-auto-attach.md @@ -0,0 +1,157 @@ +--- +Order: 40 +TOCTitle: Logpoints and auto-attach +PageTitle: Introducing Logpoints and auto-attach +MetaDescription: Introducing Logpoints and auto-attach to make debugging easier and simpler to use in Visual Studio Code +MetaSocialImage: /assets/blogs/2018/07/12/debugger.png +Date: 2018-07-12 +ShortDescription: Introducing Logpoints and auto-attach to make debugging easier and simpler to use +Author: Kenneth Auchenberg +--- +# Introducing Logpoints and auto-attach + +July 12, 2018 Kenneth Auchenberg, [@auchenberg](https://twitter.com/auchenberg) + +Over the past few months we have been busy improving the debugging experience in Visual Studio Code, and in this post, I'm going to talk about how we think about debugging, present the feedback we heard from our users, and explain the steps we are taking to make debugging easier and simpler in VS Code. + +Since the start of VS Code, we have shipped with an integrated debugging experience as we believe debugging should be an integral part of where you write and edit your source code  –– your editor. + +![VS Code debugger](debugger.png) + +The VS Code debugging experience is powered by a generic debugger UI that communicates through the Debug Adapter Protocol (DAP) with a specific type of VS Code extension that we call a Debug Adapter (DA). The DA talks to a real debugger and translates between the DAP and the runtime specific debug protocol or API of the debugger. + +This means that the core of VS Code is fully decoupled from the specific debugger and this architecture allows VS Code to debug anything, as long as there's a Debug Adapter available, as illustrated here: + +
+ +![VS Code debugging architecture](debugging_architecture.png) + +
+ +## Observations and pain points + +Today there are a large group of satisfied developers debugging with VS Code on a regular basis, but, as a part of our mission, we want to make debugging easier and available to more developers. + +To this end, we began conversations to better understand the pain points of debugging in VS Code and learn why some developers aren't using our debugger at all. + +Here are our observations: + +### Debug configuration is hard to get right + +VS Code is a general editor with a generic debugger and is not specialized for a particular stack or runtime. For this reason, we can't provide an opinionated default debug configuration that will work for everyone. + +This means that VS Code requires you to configure settings for the debugger as well as specify how you want to start your runtime with the right parameters, etc. + +We recognize that this can be hard to get right, but we don't see a way to completely eliminate debug configuration for everyone. However, we do believe that debug configuration can be simplified and depending on the context, reduced to a minimum. + +I'll get back to this later. + +### Confusion between launch and attach configs + +In VS Code, we have two core concepts for debugging: **Launch** and **Attach**, which handle two different workflows and segments of developers. Depending on your workflow, it can be confusing to know what type of configuration is appropriate for your project. + +If you come from a browser DevTools background, you aren't used to the concept of "launching from your tool" since your browser instance is already open. When you open DevTools, you are simply **attaching** DevTools to your open browser tab. On the other hand, if you come from a Java background, it's quite normal to have your editor **launch** your Java process for you, and your editor automatically attaches its debugger to the newly launched process. + +The best way to explain the difference between **launch** and **attach** is to think about [launch configurations](/docs/editor/debugging#_launch-configurations) as a recipe for how to start your app in debug mode **before** VS Code attaches to it, while an [attach config](/docs/editor/debugging#_launchjson-attributes) is a recipe for how to connect VS Code's debugger to an app or process that's **already** running. + +The value of [launch configurations](/docs/editor/debugging#_launch-configurations) is that they give you a way to offload some of the cognitive overhead of launching your app with the right debugging parameters by creating a configuration that's repeatable and shareable with your project and team. + +However, when we talked to developers about how they were launching their applications, we saw a pattern and made one important observation: + +**Observation**: Many developers who are using VS Code really love the Integrated Terminal and rely on command line tools to launch their applications. For many, it's a more natural workflow to run a command in the terminal followed by attaching the debugger from the editor. This is similar to opening DevTools after the browser has been launched. + +This observation was key, and we realized that many users don't want a full "magical" launch experience in their editor. They want to keep their editor as the place to edit and debug source code and use the terminal to launch apps, run build scripts, etc. This is one of the reasons why we have an Integrated Terminal experience inside VS Code, as we believe a good functional UI should co-exist and integrate well with the terminal. + +### Many developers don't use breakpoints because they are inspecting state changes + +When looking at how developers debug their applications, we also saw another interesting pattern: The use of logging instead of breakpoints. + +Logging for debugging isn't a new concept but the observation was important: + +**Observation**: Traditional debugging workflows are most focused around slowing down execution to inspect program logic, while logging workflows usually involve inspecting program state and how it changes during the normal execution of an application. The fundamental observation here is that the two techniques are used for different debugging purposes. + +This observation is especially relevant for JavaScript developers, who mostly deal with the complexity of managing state, and this might explain why [most JavaScript developers still prefer to add console.log's](https://christianheilmann.com/2017/07/08/debugging-javascript-console-loggerheads/) to their source code instead of using a script debugger. + +
+ + + +
+ +## Auto-attaching to Node processes + +When reflecting on how some developers are using the Integrated Terminal to launch their debugging session, we saw a unique opportunity emerge. By leveraging the contextual information we have inside VS Code from your editor and Integrated Terminal, we could detect your context and reason about your intent to debug, and this could provide a much simpler debugging experience for Node.js developers. + +So in [our March iteration](https://code.visualstudio.com/updates/v1_22#_node-debugging) of VS Code, we released a new feature that called **Auto Attach for Node**, that enables the Node debugger to automatically attach to Node.js processes that have been launched in debug mode from VS Code's Integrated Terminal. + +You enable auto attach by running **Debug: Toggle Auto Attach** command from the Command Palette, and once activated you can toggle auto attach from the Status Bar as well. + +
+ +![Auto attach](auto-attach.gif) + +
+ +This feature completely eliminates any debug configuration, as we interpret any Node.js process started with `node --inspect` as an intent to debug. When combined with the Integrated Terminal, it is a much simpler debugging experience that allows developers to launch their app in their own way, while eliminating debug configuration at the same time! 🎉 + +## NPM scripts and debugging + +Many Node.js developers rely on [npm scripts](https://docs.npmjs.com/misc/scripts) to launch applications or start debugging sessions, and we have some great news on that front too: Auto-attach also works with npm scripts. If you run `npm run debug` and the `"debug"` script is `"node --inspect"` or any other command that includes `--inspect`, then auto attach will detect that and attach the debugger 🎉 + +We also recognized that some developers wanted a more visual way to find and run their npm scripts, so in [our April 2018 iteration](https://code.visualstudio.com/updates/v1_23#_npm-script-running), we added a new NPM scripts explorer (enabled by the setting `"npm.enableScriptExplorer"`) that allows you to browse and run your NPM scripts directly from the UI. As a part of our work to simplify debug configuration, we also made it possible to start Node.js debugging directly from the explorer, without having to create a debug configuration. + +If you have a npm script that includes a debugging argument like `--inspect`, we'll automatically detect this and provide a debug action that launches the debugger, as seen here: + +![NPM scripts](npm_scripts.png) + +## Introducing Logpoints + +Based on the learning that logging is an important debugging technique, we saw an opportunity to add state inspection to our existing debugging experience. In [the March iteration](https://code.visualstudio.com/updates/v1_22#_logpoints) of VS Code, we released the first implementation of a debugging feature that we call Logpoints. + +A Logpoint is a breakpoint variant that does not "break" into the debugger but instead logs a message to the console. + +![Logpoints](logpoints.gif) + +The concept for Logpoints isn't new, and over the past few years, we have seen different flavors of this concept in tools like [Visual Studio](https://codewala.net/2018/01/25/tracepoint-an-awsome-feature-of-visual-studio/), [Edge DevTools](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide/debugger) and [GDB](https://sourceware.org/gdb/onlinedocs/gdb/Tracepoints.html) under several names such as Tracepoints and [Logpoints](https://devblogs.microsoft.com/visualstudio/debug-live-apps-in-azure-with-the-snappoints-and-logpoints-preview). + +### Why and when to use Logpoints? + +Logpoints are based on the observation that in many cases, you don't want to stop execution in a particular part of your application, but instead you want to inspect how state mutates throughout the lifetime of the application. + +Logpoints allows you to "inject" on-demand logging statements into your application logic, just like if you had added logging statements into your application before starting it. Logpoints are injected at execution time and not persisted in the source code, so you don't have to plan ahead but can inject Logpoints as you need them. Another nice benefit is that you don't have to worry about cleaning up your source code after you are finished debugging. + +For JavaScript developers, this means that you don't have to worry about leaving `console.log`s behind anymore  –– just use Logpoints! Even better, you can combine `console.log` and Logpoints. If you insert a Logpoint into a block of source code that already has `console.log`s, you'll see both types of logging statements inside the Debug Console. + +### Logpoints in cloud contexts + +Logpoints are particular useful in cloud contexts (or any remote context really), as they enable you to inject logging into remote environments without having to redeploy your applications. Equally important, you don't halt script execution with Logpoints, so your users aren't affected unlike halting the running application on a regular breakpoint. + +You can read more about how to use [Logpoints for Node.js on Azure here](https://medium.com/@auchenberg/introducing-remote-debugging-of-node-js-apps-on-azure-app-service-from-vs-code-in-public-preview-9b8d83a6e1f0). + +### Supported languages + +Since the first release of Logpoints in VS Code, we have seen a growing adoption by VS Code Debug Adapters, and today there is Logpoint support for the following languages: + +- [Node.js debugger](https://github.com/Microsoft/vscode-node-debug2/) +- [Chrome debugger](https://github.com/Microsoft/vscode-chrome-debug/) +- [Firefox debugger](https://github.com/hbenl/vscode-firefox-debug/commit/0c90a695e304bb54402ada129f8fafae462718f5) +- [Microsoft Edge debugger](https://github.com/Microsoft/vscode-edge-debug2) +- [React Native Debugger](https://github.com/Microsoft/vscode-react-native) +- [Python Debugger](https://github.com/Microsoft/vscode-python) +- [Dart debugger](https://github.com/Dart-Code/Dart-Code) +- [Lua debugger](https://github.com/actboy168/vscode-lua-debug) +- [Java Debugger](https://github.com/Microsoft/java-debug/pull/184) + +### Logpoints in the VS Code + +If you are interested in adding Logpoint support in your Debug Adapter for VS Code, please take a look at [these changes](https://github.com/Microsoft/vscode-debugadapter-node/commit/aeda2ba8ae526906585a5ccb7d8346a71b83ed10) in the protocol. You can also look at the above debug adapters to see how each runtime has chosen to implement Logpoints. + +## Next steps + +That's it for now, but we aren't finished. In our [July iteration](https://github.com/Microsoft/vscode/issues/53850), we are making improvements to auto-attach in order to aid discoverability ([#53640](https://github.com/Microsoft/vscode/issues/53640)), based on user feedback. + +We hope the introduction of auto-attach, NPM scripts explorer, and Logpoints are going to make it easier to debug with VS Code. As always, we are eager to hear your feedback, so reach out to us at [GitHub](https://github.com/Microsoft/vscode) or [@code on Twitter](https://twitter.com/code). + +On behalf of the VS Code team: Happy Coding! + +/Kenneth Auchenberg - [@auchenberg on Twitter](https://twitter.com/auchenberg) diff --git a/blogs/2018/07/12/logpoints.gif b/blogs/2018/07/12/logpoints.gif new file mode 100644 index 0000000000000000000000000000000000000000..2f692b52fc3d1ecd9f163c0b40f468b3559fbc9a --- /dev/null +++ b/blogs/2018/07/12/logpoints.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dc80150db6320dc5cb14458bdde78c3dd0fd5a99fde28a75d019fa53455c33d8 +size 1582288 diff --git a/blogs/2018/07/12/npm_scripts.png b/blogs/2018/07/12/npm_scripts.png new file mode 100644 index 0000000000000000000000000000000000000000..d1dc674d49c8633a09cdfd81585bce8d635eac39 --- /dev/null +++ b/blogs/2018/07/12/npm_scripts.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8509e51c928e372435dd73e331b82d4ab3ca08d3d3aaed61479e391a2fdfc996 +size 324580 diff --git a/blogs/2018/08/07/breakpoint.png b/blogs/2018/08/07/breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..a628c1ee84f0738f3cdcb93bf1d0d9cf438c9d9e Binary files /dev/null and b/blogs/2018/08/07/breakpoint.png differ diff --git a/blogs/2018/08/07/debug-adapter-protocol-website.md b/blogs/2018/08/07/debug-adapter-protocol-website.md new file mode 100644 index 0000000000000000000000000000000000000000..f1288668cd46282576459932df5d971a4b8b97c6 --- /dev/null +++ b/blogs/2018/08/07/debug-adapter-protocol-website.md @@ -0,0 +1,124 @@ +--- +Order: 41 +TOCTitle: New home for Debug Adapter Protocol +PageTitle: A new home for the Debug Adapter Protocol +MetaDescription: A new home for the Debug Adapter Protocol +MetaSocialImage: /assets/blogs/2018/08/07/with-DAP.png +Date: 2018-08-07 +ShortDescription: The new Debug Adapter Protocol website +Author: André Weinand +--- +# New home for the Debug Adapter Protocol + +August 7, 2018 André Weinand, [@weinand](https://twitter.com/weinand) + +One goal of the July milestone was to move the **Debug Adapter Protocol** -- which was hiding itself in a somewhat obscure [GitHub project](https://github.com/Microsoft/vscode-debugadapter-node) -- to a more prominent website (see feature request [#19636](https://github.com/Microsoft/vscode/issues/19636)). + +This blog provides some background about protocols, the Debug Adapter Protocol, and the motivation behind the move. + +## Why the need for decoupling with protocols? + +From another [blog](https://code.visualstudio.com/blogs/2016/06/27/common-language-protocol): + +**_"Visual Studio Code is an editor for any developer, no matter what programming language you use."_** + +This promise is based on (at least) two pillars: + +- An extensible tool platform and ecosystem where everyone can easily contribute. +- Technology that makes it easy to add great tool support for any programming language. + +Supporting a programming language from a development tool means: + +- Rich editing support based on a deep understanding of a language (AKA "language smartness"). +- Debugging support for the language integrated into the editing tool. + +The latter might come as a surprise to some, but it was always our firm belief that debugging is an integral part of where the source code is written: the editor. Debugging is an important part of the development "inner loop." + +But adding a debugger for a new language to an IDE or editor is a significant effort as the list of standard debugging features is not small: + +- Source, function, conditional, inline breakpoints, and [logpoints](https://code.visualstudio.com/blogs/2018/07/12/introducing-logpoints-and-auto-attach). +- Variable values shown in hovers or inlined in the source. +- Multi-process and multi-thread support. +- Navigating through complex data structures. +- Watch expressions. +- Debug console for interactive evaluation with autocomplete (REPL). + +Implementing these features for a new language is not only a significant effort, it is also frustrating that this work must be repeated for each development tool, as each tool uses different APIs for implementing its user interface. + +This results in lots of duplicated functionality (and implementation) as visualized by the blue boxes in the following picture: + +![without Debug Adapter Protocol](without-DAP.png) + +When we started the work on Visual Studio Code, we always envisioned decoupling the "frontend" UI from the language specific "backend" implementation as much as possible. We wanted to do this for both language smartness and debugging support. + +Today we believe that we have achieved this ambitious goal: + +We have created two abstract protocols that allow for decoupling the editing and debugging user interfaces in the "frontend" from the language specific smartness and debugging functionality provided by "backend" components. + +The "deep understanding of a language" is surfaced by the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) and the "debugging support" by the Debug Adapter Protocol (DAP). + +## The Debug Adapter Protocol + +The idea behind the Debug Adapter Protocol is to standardize an abstract protocol for how the debugging component of a development tool communicates with concrete debuggers or runtimes. + +Since it is unrealistic to assume that existing debuggers or runtimes would adopt this protocol any time soon, we instead designed an **intermediary** component to take over the role of adapting an existing debugger or runtime API to the Debug Adapter Protocol. This intermediary becomes the Debug Adapter which explains the name of the protocol: Debug Adapter Protocol. + +Here’s an example of how a development tool could use the DAP to communicate with a Debug Adapter for the popular "gdb" debugger: + +![breakpoint](breakpoint.png) + +We assume that the user has already started a debug session, but is currently stopped at the entry point of their program and wants to set (and later hit) a breakpoint. + +- The user sets one or more breakpoints in a specific source file by clicking in the breakpoint gutter. The development tool sends a `setBreakpoints` request to the Debug Adapter which registers the breakpoint with the gdb debugger. +- The user then presses the **Continue** button to resume execution. The tool sends a `continue` request to the Debug Adapter which translates this into the corresponding gdb command. +- Some time later, the breakpoint is hit and the Debug Adapter receives some notification from gdb and translates this into a DAP `stopped` event which gets sent to the development tool. +- In response to this `stopped` event, the development tool updates its UI and shows a stacktrace view. This triggers a `stacktrace` request which returns all the information that is displayed for the individual stack frames. +- If the user selects one stack frame, the development tool requests the variables of that frame with a `variables` request. + +For [historical reasons](https://github.com/Microsoft/vscode-debugadapter-node/issues/58), DAP uses a JSON-based wire-format inspired by the (now obsolete) [V8 Debugging Protocol](https://github.com/dtretyakov/node-tools/wiki/Debugging-Protocol). Please note that this format is similar to but not compatible with the JSON-RPC used in the LSP. + +After this short example of DAP communication, let's review the characteristics of the DAP approach: + +![with Debug Adapter Protocol](with-DAP.png) + +The picture shows two important benefits of the DAP approach: + +- Debug Adapters can be shared between different development tools, which helps amortize their development cost. +- The Debug Adapter Protocol is not tied to VS Code and can be used as the foundation for a generic debugger UI in other development tools. + +These characteristics are similar to those of the Language Server Protocol published on its own [website](https://microsoft.github.io/language-server-protocol/) in 2016. + +## A new home for the DAP + +Now we have followed suit for the Debug Adapter Protocol by moving the DAP specification from its [old location](https://github.com/Microsoft/vscode-debugadapter-node) to a new website [https://microsoft.github.io/debug-adapter-protocol](https://microsoft.github.io/debug-adapter-protocol/) and a corresponding repository [https://github.com/Microsoft/debug-adapter-protocol](https://github.com/Microsoft/debug-adapter-protocol). + +This move should emphasize that the Debug Adapter Protocol in not specific to Visual Studio Code. For example, Visual Studio is now also [supporting this protocol](https://devblogs.microsoft.com/visualstudio/adding-support-for-debug-adapters-to-visual-studio-ide). + +In the new location we provide: + +- An [overview and introduction](https://microsoft.github.io/debug-adapter-protocol/overview) to the protocol. +- The [protocol specification](https://microsoft.github.io/debug-adapter-protocol/debugAdapterProtocol.json) as a machine-processable [JSON-schema](http://json-schema.org). +- [Detailed documentation](https://microsoft.github.io/debug-adapter-protocol/specification) automatically generated from the protocol specification. +- [Debug Adapters](https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/) implementing the protocol. +- [Development tools](https://microsoft.github.io/debug-adapter-protocol/implementors/tools/) hosting the protocol. +- [SDKs](https://microsoft.github.io/debug-adapter-protocol/implementors/sdks/) supporting the protocol. +- Bugs, feature requests, and pull requests can be created under the [Issues](https://github.com/Microsoft/debug-adapter-protocol/issues) section of the new repository. + +The [old location](https://github.com/Microsoft/vscode-debugadapter-node) will continue to host the source for the three npm modules for DAP: + +- [vscode-debugprotocol](https://www.npmjs.com/package/vscode-debugprotocol) +- [vscode-debugadapter](https://www.npmjs.com/package/vscode-debugadapter) +- [vscode-debugadapter-testsupport](https://www.npmjs.com/package/vscode-debugadapter-testsupport) + +## What's Next? + +Since the Debug Adapter Protocol has already been available for quite some time, the move to a new website is not really an inception, but just a move to a new home... + +We'd like to invite all existing and future users of the DAP to visit our new home and continue the collaboration there. For example, you can help to keep the list of supporting tools and implementations up to date by submitting pull requests in GitHub against these Markdown files: +[Debug Adapters](https://github.com/Microsoft/debug-adapter-protocol/blob/gh-pages/_implementors/adapters.md), +[Tools](https://github.com/Microsoft/debug-adapter-protocol/blob/gh-pages/_implementors/tools.md), and +[SDKs](https://github.com/Microsoft/debug-adapter-protocol/blob/gh-pages/_implementors/sdks.md). + +On behalf of the VS Code team: Happy Coding! + +André Weinand -  [@weinand on Twitter](https://twitter.com/weinand) diff --git a/blogs/2018/08/07/with-DAP.png b/blogs/2018/08/07/with-DAP.png new file mode 100644 index 0000000000000000000000000000000000000000..045384b82f3c27845d1ecf8c177a7caae9bde6e5 Binary files /dev/null and b/blogs/2018/08/07/with-DAP.png differ diff --git a/blogs/2018/08/07/without-DAP.png b/blogs/2018/08/07/without-DAP.png new file mode 100644 index 0000000000000000000000000000000000000000..14349509e14593878ab7b443ef9de1a81868685d Binary files /dev/null and b/blogs/2018/08/07/without-DAP.png differ diff --git a/blogs/2018/09/10/github_pr_hero.png b/blogs/2018/09/10/github_pr_hero.png new file mode 100644 index 0000000000000000000000000000000000000000..13566f86330c069cfa4209a3b8e37e1605042906 --- /dev/null +++ b/blogs/2018/09/10/github_pr_hero.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7fa5abeb13d40e4ca410a527c9b668ad17740e72cbe40b1ab17f0c8bdf08880b +size 227982 diff --git a/blogs/2018/09/10/github_pr_overview.png b/blogs/2018/09/10/github_pr_overview.png new file mode 100644 index 0000000000000000000000000000000000000000..13d6077531a1753fd15771c2ca1dc2724400a4f0 --- /dev/null +++ b/blogs/2018/09/10/github_pr_overview.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:36c7b11d25ce5da0b7319ce834f43c7577572a635ee3e1441419eb068581631e +size 674238 diff --git a/blogs/2018/09/10/introducing-github-pullrequests.md b/blogs/2018/09/10/introducing-github-pullrequests.md new file mode 100644 index 0000000000000000000000000000000000000000..08c3ea422dd990582ec6746830442696649bc6a9 --- /dev/null +++ b/blogs/2018/09/10/introducing-github-pullrequests.md @@ -0,0 +1,64 @@ +--- +Order: 42 +TOCTitle: GitHub Pull Requests +PageTitle: Introducing GitHub Pull Requests for Visual Studio Code +MetaDescription: Introducing GitHub Pull Requests for Visual Studio Code +MetaSocialImage: /assets/blogs/2018/09/10/github_pr_hero.png +Date: 2018-09-10 +ShortDescription: Introducing GitHub Pull Requests for Visual Studio Code +Author: Kenneth Auchenberg +--- +# GitHub Pull Requests in Visual Studio Code + +September 10, 2018 Kenneth Auchenberg, [@auchenberg](https://twitter.com/auchenberg) + +Like many other open source projects, the [Visual Studio Code community collaborates](https://github.com/Microsoft/vscode) through [pull requests](https://github.com/Microsoft/vscode/pulls) to land fixes and new features. Starting this past spring, our team has been working to bring you a new integrated pull request experience so that you can collaborate, comment, review, and validate GitHub pull requests directly from within Visual Studio Code. + +Today, we are announcing the public preview of [GitHub Pull Requests for Visual Studio Code](https://aka.ms/vscodepr-download), closing a gap in the workflow that we and millions of engineers experience every day: The ability to review source code where it was written – inside the editor. + +![hero](github_pr_hero.png) + +## Review and manage Pull Requests + +The new GitHub Pull Requests extension is designed to help you review and manage pull requests (PR) from within Visual Studio Code, including: + +- Ability to authenticate and connect Visual Studio Code to GitHub. +- List and browse PRs from within Visual Studio Code. +- Interact with PRs in-editor, including in-editor commenting with Markdown support. +- Validate PRs from the editor with a new local `checkout and run` workflow for rich language features such as Go To Definition and IntelliSense. +- Terminal integration so that the Visual Studio Code UI and command line tools like `git` can co-exist. + +![overview](github_pr_overview.png) + +## Collaboration with GitHub + +As part of our broader efforts to bring pull requests into Visual Studio Code in the past year, we reached out to numerous partners. After learning that the GitHub Editor team was already thinking along these lines, we began to work together in April to create a new pull request experience in Visual Studio Code. We developed a new extension to create and review pull requests integrated directly into Visual Studio Code through a set of new Visual Studio Code extension APIs. + +## A more natural PR experience + +Today when reviewing source code, many of us are forced to leave our editors to use a simplified web interface or third party review tool that presents changes in a different editor. This makes it easy to get a visual overview of the changes, but most of the time you don’t have full context of where the changes were made and how they affect surrounding source code. Being outside of your normal coding environment also means that you don’t have your favorite keyboard shortcuts, themes, and customizations. More importantly, it means that you don’t have an environment with the power to navigate the source code and validate that the changes you are reviewing actually work as expected. + +The new pull request extension changes this with a new **Pull Requests** explorer inside the Source Control view in Visual Studio Code, where you can browse and interact with pull requests. + + + +## New open extension APIs + +Our new pull requests experience is powered by a set of extension APIs that allow Visual Studio Code extension authors to create extensions that manage pull requests and their related metadata. This open extension model means that pull request providers work just like our existing source control providers and anyone can write an extension for Visual Studio Code that provides in-editor commenting and capabilities to review source code hosted on their platform. You can read more about the new APIs in our [August 2018 release notes](https://code.visualstudio.com/updates/v1_27#_comment-providers). + +If you are interested, you can read more about how we are introducing new APIs, and the details for our [extension API process here](https://github.com/Microsoft/vscode/wiki/Extension-API-process). + +## Going forward + +We are excited about bringing pull requests into Visual Studio Code, as we believe it will simplify the way you review source code. Our GitHub extension is just the first example of integrating source control platform providers for code reviews in Visual Studio Code. + +Please try out the public preview of [GitHub Pull Requests for Visual Studio Code](https://aka.ms/vscodepr-download), and as always, we are eager to hear your feedback, so don’t hesitate in reaching to us on [GitHub](https://github.com/Microsoft/vscode-pull-request-github) or [@code on Twitter](https://twitter.com/code). + +One more thing, today we are also releasing [Azure DevOps](https://azure.microsoft.com/services/devops), and the new [Azure Pipelines](https://github.com/marketplace/azure-pipelines) extension on the GitHub Marketplace. For more information, visit [https://aka.ms/azurecicd](https://aka.ms/azurecicd). + +[Kenneth Auchenberg (Microsoft)](https://twitter.com/auchenberg), Rachel Macfarlane (Microsoft), [Kai Maetzel (Microsoft)](https://twitter.com/kaimaetzel), [Peng Lyu (Microsoft)](https://twitter.com/njukidreborn) +, [Sarah Guthals (GitHub)](https://twitter.com/sarahguthals) and [Andreia Gaita (GitHub)](https://twitter.com/shana) + +and on behalf of the Visual Studio Code team: + +Happy Coding! diff --git a/blogs/2018/09/12/build.png b/blogs/2018/09/12/build.png new file mode 100644 index 0000000000000000000000000000000000000000..3b3657951ecaffafa2ce4c761f7c74e93a46d7b6 --- /dev/null +++ b/blogs/2018/09/12/build.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:24b629f7c76cb0e779fdeb0451f74224089e49949a6d8aee1a3b7b3ba2fdba78 +size 311456 diff --git a/blogs/2018/09/12/engineering-with-azure-pipelines.md b/blogs/2018/09/12/engineering-with-azure-pipelines.md new file mode 100644 index 0000000000000000000000000000000000000000..69aab42c147ebb4e330aa01de68b2be2557d6b52 --- /dev/null +++ b/blogs/2018/09/12/engineering-with-azure-pipelines.md @@ -0,0 +1,71 @@ +--- +Order: 43 +TOCTitle: Using Azure Pipelines +PageTitle: Visual Studio Code using Azure Pipelines +MetaDescription: Visual Studio Code using Azure Pipelines +MetaSocialImage: /assets/blogs/2018/09/12/social_pipelines.png +Date: 2018-09-12 +ShortDescription: Improved Engineering with Azure Pipelines +Author: João Moreno +--- +# Visual Studio Code using Azure Pipelines + +September 12, 2018 João Moreno, [@joaomoreno](https://twitter.com/joaomoreno) + +One of my responsibilities as a developer on the Visual Studio Code team is to maintain and improve our build and continuous integration (CI) infrastructure. Given the latest feature announcements from [Azure Pipelines](https://aka.ms/azurecicd), the Visual Studio Code team has dramatically changed how we leverage Microsoft's technologies to provide a better collaboration platform for both our developers as well as our users. In this blog post, I'll guide you through a bit of Visual Studio Code's history, focusing on our CI processes and tools and how they have changed over time. + +## Visual Studio Code Engineering + +Like any other open-source project, we need to have the right tooling and capabilities to receive, triage, and address as many code contributions as possible. This rings especially true in the developer tools universe, in which end users are developers themselves: they are a passionate, hard-working, and very effective group. As of this blog post, we have [148 open PRs as well as 3,482 closed ones](https://github.com/Microsoft/vscode/pulls), which sets an average of ~3 PRs/day given the 3-year project lifespan so far. It is important that we are well equipped for handling this scale of contributions, not only to keep the project development healthy but also to help give other open source projects an example of how to operate at this scale. Part of how we do this is by streamlining our workflow by [bringing the PR experience into the editor](/blogs/2018/09/10/introducing-github-pullrequests), but CI is the other important part of handling contributions at scale. + +Up until very recently, we relied on the OSS community's default choices for public continuous integration: [Travis CI](https://travis-ci.org/) for our Linux and macOS builds and [AppVeyor](https://www.appveyor.com/) for Windows. Additionally, we used [Coveralls](https://coveralls.io/) to provide detailed test coverage reports. These services provide quality reports for PRs and code branches on our public repository, as they automate [compilation](https://github.com/Microsoft/vscode/blob/master/build/lib/compilation.ts), run [code hygiene checks](https://github.com/Microsoft/vscode/blob/master/build/gulpfile.hygiene.js) and [execute several test](https://github.com/Microsoft/vscode/tree/master/test) suites, all of which is essential in order to maintain quality in a distributed team with lots of incoming contributions. This combination of services requires the understanding and maintenance of at least 3 different systems, each with its own special file formats, syntax, quirks, limitations, etc. + +## Adopting Azure Pipelines + +Earlier this year, we were reached out by the Azure Pipelines (then Visual Studio Team Services) team to try out something new. This was the outcome: + +
+ + + + +
+ +This announcement marks our move to a more streamlined continuous integration solution. Our builds now run simultaneously across all platforms, [check it out](https://aka.ms/vscode-builds): + +![VSCode Project Build Page](build.png) + +There's a lot of cool stuff which needed to happen in order for us to make the move. Let's break it down: + +1. Azure Pipelines [support for public projects](https://docs.microsoft.com/azure/devops/organizations/public) enable us to run a [public-facing Visual Studio Code project](https://dev.azure.com/vscode/VSCode/_build?definitionId=1) in which all our continuous integration builds run; +2. [Build Agents](https://docs.microsoft.com/azure/devops/pipelines/agents/agents) in Azure Pipelines have long supported the Windows, macOS, and Linux platform matrix; +3. [Microsoft-hosted agents](https://docs.microsoft.com/azure/devops/pipelines/agents/hosted) in Azure Pipelines running macOS, Linux, and Windows provide a great stack of software to build projects without worrying about build machine maintenance; +4. [YAML CI](https://docs.microsoft.com/azure/devops/pipelines/get-started-yaml) allows creating YAML definitions which are kept close to the project's sources (for which Visual Studio Code provides [great extensions](https://marketplace.visualstudio.com/search?term=yaml&target=VSCode&category=All%20categories&sortBy=Relevance)). + +Putting all of this together, we're finally able to focus on a single CI solution. The [Visual Studio Code build on Azure Pipelines](https://dev.azure.com/vscode/VSCode/_build/results?buildId=5876&view=logs) runs our compilation, hygiene checks and test suites in a single build, automatically distributing the build across different platforms. Since we're using Microsoft-hosted build agents, we don't have to worry about maintaining those machines. + +## Third Party Integrations + +Azure Pipelines also provides GitHub integration which gives us build result indicators across our GitHub project page, namely in pull requests. + +![Pull Request Integration](pr.png) + +We've also built a chat bot which hooks up to [Azure Pipeline's REST API](https://docs.microsoft.com/rest/api/vsts/build/?view=vsts-rest-4.1) and provides notifications to our internal chat when builds break. + +![Chat Bot Automation](slack.png) + +## Going forward + +My next task will be to take advantage of [code coverage reports](https://docs.microsoft.com/azure/devops/pipelines/tasks/test/publish-code-coverage-results) in order to get a better end-to-end CI flow than we had with the previous tool mix. + +Having made the jump to Azure Pipelines has proved to be a big success for us. Overall code quality is easier to reason about now since builds aren't scattered all around. We have also consolidated the number and format of our [build definition files](https://github.com/Microsoft/vscode/blob/master/build/tfs/product-build.yml). We're very happy with the change and excited about what the future holds for Azure Pipelines. + +--- + +If you'd like to learn more about public projects and Azure Pipelines, take a look at their [blog post](https://aka.ms/azurecicd). + +Would you like to give Visual Studio Code a try? [Download it now](https://code.visualstudio.com/Download) for your platform of choice. And if you're like us, and always want to run the latest and greatest, then [get our daily-built Insider release](https://code.visualstudio.com/insiders/). Do you simply want to reach out or keep in touch? Follow us [@code on Twitter](https://twitter.com/code). + +On behalf of the VS Code team: Happy Coding! + +João Moreno, [@joaomoreno](https://twitter.com/joaomoreno) diff --git a/blogs/2018/09/12/pr.png b/blogs/2018/09/12/pr.png new file mode 100644 index 0000000000000000000000000000000000000000..500c5b481362592f203298b22515d94806b1c14c --- /dev/null +++ b/blogs/2018/09/12/pr.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:48501146c62ad75be9b90f1527efdc4d0420b3fed6f47a84337daef8a291727b +size 113242 diff --git a/blogs/2018/09/12/slack.png b/blogs/2018/09/12/slack.png new file mode 100644 index 0000000000000000000000000000000000000000..6791233310efd0f347c52e4add0f2040606e3482 --- /dev/null +++ b/blogs/2018/09/12/slack.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:13203fbb8079a0fc0b597af78754b7649f6f8a40f7f43218e14be9a216e2f43f +size 171549 diff --git a/blogs/2018/09/12/social_pipelines.png b/blogs/2018/09/12/social_pipelines.png new file mode 100644 index 0000000000000000000000000000000000000000..70885349cbba568e48fe45660cd1dd3f0171b18a Binary files /dev/null and b/blogs/2018/09/12/social_pipelines.png differ diff --git a/blogs/2018/09/12/tweet.png b/blogs/2018/09/12/tweet.png new file mode 100644 index 0000000000000000000000000000000000000000..eee937a5215c414c9ce69af52c4146e2fe6ac8e7 --- /dev/null +++ b/blogs/2018/09/12/tweet.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d5ab0dfd5da97e9b05de37e7031c4c4876fc2a4bdc1650ccd9652b882ac85439 +size 139585 diff --git a/blogs/2018/11/26/event-stream.md b/blogs/2018/11/26/event-stream.md new file mode 100644 index 0000000000000000000000000000000000000000..3ac35bb73b372789b47894f17eb98827dc95f68d --- /dev/null +++ b/blogs/2018/11/26/event-stream.md @@ -0,0 +1,95 @@ +--- +Order: 44 +TOCTitle: Event-Stream Package Security Update +PageTitle: Event-Stream Package Security Update +MetaDescription: Event-Stream Package Security Update +Date: 2018-11-26 +ShortDescription: Event-Stream Package Security Update +Author: Kai Maetzel +--- +# Event-Stream Package Security Update + +**Update**: December 7, 2018 + +We have been working with extension authors to get their extensions and dependencies updated. + +Below is the current list of blocked extensions: + +* `beisen.codecake-extension` +* `DrMueller.ts-arrange2` +* `JacobeanResearchandDevelopmentLLC.vscode-scxml-preview` +* `joaquin6.package-watch` +* `jonsmithers.open-in-vim` +* `KazuoCode.gthubsum` +* `MaxGotovkin.tslens` +* `mf.magicspace` +* `Restbird.vscode-restbird` +* `rijndael.vscode-ursharp` +* `roboceo.robojsx-plugin` +* `taosheng.less-class` +* `taosheng.uyun-class` +* `taosheng.uyun-less-class` +* `tboevil.webpaste` +* `tintrinh.php-refactor` +* `xuyl.vue-recommend-style` + +--- + +November 26, 2018 Kai Maetzel, [@kaimaetzel](https://twitter.com/kaimaetzel) + +You might already have heard that the popular event-stream NPM package includes a malicious dependency. The details can be found in the following GitHub issue: [https://github.com/dominictarr/event-stream/issues/116](https://github.com/dominictarr/event-stream/issues/116). This vulnerability has been in existence for about two months but was only recently discovered. + +>**TL;DR**: Visual Studio Code is not affected by the industry-wide NPM `event-stream` package security issue, and we've proactively protected our user base by temporarily removing extensions affected by this package from the VS Code Marketplace. + +We immediately checked if and how we are affected. First, we scanned Visual Studio Code. Both product installs of Visual Studio Code (Stable as well as Insiders) are safe. + +Secondly, we scanned all extensions in the VS Code Marketplace. We identified several extensions as affected. We decided to take aggressive actions to protect our users as well as the authors of those extensions and to automatically uninstall those extensions. Users don’t need to take any action to remove those extensions. The extensions will also be unlisted from the Marketplace. + +At the time of the scan, the following extensions contained the malicious code: + +* `aoisupersix.bve5-language-support` +* `apollographql.vscode-apollo` +* `ardenivanov.svelte-intellisense` +* `ballerina.ballerina` +* `BattleBas.kivy-vscode` +* `cesium.gltf-vscode` +* `christianvoigt.argdown-vscode` +* `codemooseus.vscode-devtools-for-chrome` +* `curlybracket.vlocode` +* `ivory-lab.jenkinsfile-support` +* `JacobeanResearchandDevelopmentLLC.vscode-scxml-preview` +* `joe-re.sql-language-server` +* `jomiller.rtags-client` +* `jorithvdheuvel.webdav` +* `KazuoCode.gthubsum` +* `kddejong.vscode-cfn-lint` +* `Koihik.vscode-lua-format` +* `myxvisual.vscode-ts-uml` +* `OptimaSystems.vscode-apl-language-client` +* `Paul-Ehigie-Paul.nativescript-extend` +* `qoretechnologies.qorus-vscode` +* `quantum.quantum-devkit-vscode` +* `ritwickdey.LiveServer` +* `rkoubou.ksp` +* `roboceo.robojsx-plugin` +* `salbert.comment-ts` +* `SiteGo.spgo` +* `terminus.tangram-vscode-plugin` +* `tintrinh.php-refactor` +* `tomoki1207.pdf` +* `vlopes11.advpls-client` +* `webhint.vscode-webhint` +* `wix.stylable-intelligence` +* `Yseop.vscode-yseopml` +* `zfzackfrost.commentbars` +* `Zowe.vscode-extension-for-zowe` + +We are in the process of notifying the authors of those extensions. Once the authors have updated their extensions and we have received their notification, we will verify the update. You will then be able to reinstall the extension from the Marketplace. + +A note to extension authors: When you generated an extension with the `yeoman` code generator, you may have installed the malicious code as part of the dev dependencies. Delete your `node_modules` folder, clean your npm cache with `npm cache clean --force`, and rerun `npm install`. + +Extension authors needs to update the `vscode` module to `1.1.22`. + +We'll keep you posted. + +[Kai Maetzel (Microsoft)](https://twitter.com/kaimaetzel) diff --git a/blogs/2018/12/04/CPlusPlus.gif b/blogs/2018/12/04/CPlusPlus.gif new file mode 100644 index 0000000000000000000000000000000000000000..b008fc60f8945b795f1b13f0ccb7ab50660aacd6 --- /dev/null +++ b/blogs/2018/12/04/CPlusPlus.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:58c13f7b0d3f772e930be3b5dfbabea3868bc88f4c24e5324462b870cc746629 +size 1719266 diff --git a/blogs/2018/12/04/CSharp.gif b/blogs/2018/12/04/CSharp.gif new file mode 100644 index 0000000000000000000000000000000000000000..84ce8998de01352a50d667df9844b996f027277c --- /dev/null +++ b/blogs/2018/12/04/CSharp.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:17ea134f696758cfafa9ec22428b76e2577fee3ceca02a8f2f690f82ea7d038c +size 2245750 diff --git a/blogs/2018/12/04/CrossRepoJump.gif b/blogs/2018/12/04/CrossRepoJump.gif new file mode 100644 index 0000000000000000000000000000000000000000..54260dfd552727067d14f65a46a94edcc2e4b8ba --- /dev/null +++ b/blogs/2018/12/04/CrossRepoJump.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bd362374b23f6284a14677355d489de665033fb9001e0ef9cd34721803e15a8a +size 1850798 diff --git a/blogs/2018/12/04/rich-navigation.md b/blogs/2018/12/04/rich-navigation.md new file mode 100644 index 0000000000000000000000000000000000000000..ad6b0151200f4bb8b74fd75be2b21ad8788a1f19 --- /dev/null +++ b/blogs/2018/12/04/rich-navigation.md @@ -0,0 +1,56 @@ +--- +Order: 45 +TOCTitle: Rich Code Navigation +PageTitle: Rich Code Navigation +MetaDescription: First look at a rich code navigation experience in Visual Studio +Date: 2018-12-04 +ShortDescription: First look at a rich code navigation experience in Visual Studio +Author: Jonathan Carter +--- +# First look at a rich code navigation experience + +December 4, 2018 Jonathan Carter, [@lostintangent](https://twitter.com/LostInTangent) + +Pull requests are a critical collaboration tool for millions of developers every day, facilitating asynchronous code reviews and the distribution of knowledge amongst teams and open source communities. Because of this widespread utility and adoption, any advancement to the PR review workflow can have a significant impact on developer productivity, product quality and release velocity. + +In September, along with GitHub, [we announced the GitHub Pull Requests extension](https://code.visualstudio.com/blogs/2018/09/10/introducing-github-pullrequests), which enabled developers to review source code in the same place they write it: inside their familiar and highly-customized editor. Today, we're excited to share a sneak peek of a new experience that will further enhance in-editor PR reviews with support for **rich, multi-repository code navigations**. + + + +## Say goodbye to superficial reviews + +To thoroughly review a pull request, you need to understand the context of its changes and how they impact the broader codebase. Today, many developers do "lightweight reviews" in their browser, which provides an extremely convenient workflow, but makes it easy to miss much-needed context (for example, "Does this change break any consumers of the API?"). The [GitHub Pull Requests](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension improved that experience by allowing you to leverage the capabilities of your developer environment to build and navigate the source code under review, but still requires you to checkout branches locally, and have the necessary platform SDKs and language extensions installed. Doing this for every PR can require a significant amount of time and context switches, which leaves you with the choice between the convenience of quickly reviewing remote PRs, or the power of reviewing them in your local editor. **We think developers should have both**. + +The rich code navigation experience we're building helps developers keep track of the pull requests they're interested in from within their development environment (via the [Visual Studio](https://marketplace.visualstudio.com/items?itemName=GitHub.GitHubExtensionforVisualStudio) and [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extensions), and at any time, begin seamlessly navigating changes across remotely-hosted PRs, without needing to checkout those topic branches locally. Specifically, it enhances files that you open from the *GitHub Pull Requests* view with the same code navigation capabilities that drives other editor experiences (e.g. hover info, go to definition, find all references), but in this case, **powered entirely by the cloud**. We believe this can enable teams to be more productive, and make superficial reviews a thing of the past. + +![Navigating a csharp PR](CSharp.gif) + +*Navigating a C#-based PR on macOS, without even having the C# extension or .NET Core installed.* + +![Navigating a C++ PR](CPlusPlus.gif) + +*Navigating a C++-based PR on macOS, without even having the C++ extension installed.* + +## Navigate all the things + +With this experience, you can navigate to symbols (e.g. classes, functions, properties) defined within the file you’re reviewing, within other files that were changed as part of the PR, as well as within arbitrary files in the same repository. This way, your ability to understand changes within the context of the entire codebase isn’t limited by the scope of the PR or your local environment. + +Additionally, if the PR you're reviewing makes use of dependencies in external repos, or includes APIs that are consumed by code in external repos, you can directly navigate to those sources as well! This way, you can fully—and more importantly, quickly—assess the impact of a change, **regardless how your application is organized in version control**. We believe this is an extremely powerful capability, especially as more teams are building multi-repository applications/microservices and relying heavily on OSS. + +![Navigating into a Mobx repo](CrossRepoJump.gif) + +*Navigating directly into the [MobX repo](https://github.com/mobxjs/mobx) on GitHub from an [external](https://github.com/lostintangent/vsls-guestbook/pull/11/files#diff-babc63cbfdb83a46e935f16e3eb9066fR20) reference to its [observable](https://github.com/mobxjs/mobx/blob/master/src/api/observable.ts#L183) function.* + +## Community-focused design + +Behind the scenes, this experience is powered by an addition to the [Language Server Protocol](https://microsoft.github.io/language-server-protocol) (LSP), which is already the foundation for language support across a number of [tools](https://microsoft.github.io/language-server-protocol/implementors/tools), such as Visual Studio and Visual Studio Code. This proposal, called the Language Server Index Format (LSIF, pronounce like "else if"), provides a means for language servers to persist their runtime intelligence, so that it can be subsequently used to answer LSP requests at-scale (for example, hover and go to definition). Additionally, the data model that LSIF defines enables repositories to be represented via rich graphs of source code, and the relationships that code has with external repositories. + +As part of building out this service, we've begun implementing LSIF support for various languages (JavaScript, TypeScript, C++, and C#), and we're extremely excited with the results so far. However, in order for this effort to be successful, it's critical that we partner with the community on both the standard, as well as additional language implementations. To learn more about LSIF, and contribute to this conversation moving forward, check out the [the draft LSIF specification](https://aka.ms/lsif-spec). + +## We need your feedback! + +We're excited to share this first look of the rich code navigation experience! We've got a lot of work left to do before this becomes something you can try out, but we wanted to start an open conversation with the community about what we're working on. If you're interested in chatting with our team, and taking part in a potential preview, you can sign-up [here](http://aka.ms/rich-nav-signup). We look forward to sharing more updates in the near future! + +Happy reviewing! + +Jonathan, [@lostintangent](https://twitter.com/LostInTangent) diff --git a/blogs/2019/02/19/foldingRange.png b/blogs/2019/02/19/foldingRange.png new file mode 100644 index 0000000000000000000000000000000000000000..a5ad00176be08ce938f254cb9b6f1418fb958848 Binary files /dev/null and b/blogs/2019/02/19/foldingRange.png differ diff --git a/blogs/2019/02/19/hover.png b/blogs/2019/02/19/hover.png new file mode 100644 index 0000000000000000000000000000000000000000..d6af021525a0364da800f209e89f86f91abfda9a Binary files /dev/null and b/blogs/2019/02/19/hover.png differ diff --git a/blogs/2019/02/19/hoverResult.png b/blogs/2019/02/19/hoverResult.png new file mode 100644 index 0000000000000000000000000000000000000000..33705d1007afe740b4a43db17ee7e3f336454206 Binary files /dev/null and b/blogs/2019/02/19/hoverResult.png differ diff --git a/blogs/2019/02/19/lsif.md b/blogs/2019/02/19/lsif.md new file mode 100644 index 0000000000000000000000000000000000000000..9d89a9373b7ba71897ac57e6234e80650e9667f7 --- /dev/null +++ b/blogs/2019/02/19/lsif.md @@ -0,0 +1,142 @@ +--- +Order: 46 +TOCTitle: Language Server Index Format +PageTitle: Language Server Index Format +MetaDescription: Rich Code Navigation without Checkout +Date: 2019-02-19 +ShortDescription: Rich Code Navigation without Checkout +Author: Dirk Bäumer +--- +# The Language Server Index Format (LSIF) + +February 19, 2019 by Dirk Bäumer + +## Rich code navigation without checkout + +As a developer, you spend a lot of your time reading and reviewing code and not necessarily authoring new source code. For example, you may want to browse an existing codebase in a repository like GitHub or you may want to review a colleague's Pull Request. + +Typically you would check out a branch or clone a repository pulling down the source code onto your local machine, open your preferred development tool, and then finally you can read and navigate the code. Wouldn't it be cool if you could do this without first cloning the repo? Imagine getting intelligent code features like hover information, Go to Definition, and Find All References without having to download source code. The blog post, [First look at a rich code navigation experience](https://code.visualstudio.com/blogs/2018/12/04/rich-navigation), illustrates this scenario for a Pull Request review. + +The goal of the Language Server Index Format (LSIF, pronounced like "else if") is to support rich code navigation in development tools or a Web UI without needing a local copy of the source code. The format is similar in spirit to the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP), which simplifies the integration of rich code editing capabilities into a development tool. + +Why not simply use an existing LSP language server? The LSP provides rich code authoring features like auto complete, format on type, and rich code navigation. To provide these features efficiently, a language server requires all source code files be available on a local disk. LSP language servers may also read parts or all of the files into memory and compute abstract syntax trees to power these features. The goal of the Language Server Index Format is to augment the LSP protocol to support rich code navigation features without these requirements. The LSIF defines a standard format for language servers or other programming tools to emit their knowledge about a code workspace. This persisted information can later be used to answer LSP requests for the same workspace without running a language server. + +## Language Server Index Format + +LSIF builds on LSP and it uses the same data types as defined in LSP. At a high level, LSIF models the data returned from language server requests. Same as LSP, LSIF doesn't contain any program symbol information nor does the LSIF define any symbol semantics (for example, what makes the definition of a symbol or whether a method overrides another method). The LSIF therefore doesn't define a symbol database, which is consistent with the LSP approach. + +Using the existing LSP data types as the base for LSIF has another advantage as LSIF can easily be integrated into tools or servers which already understand LSP. + +Let's have a look at an example. We start with a simple Typescript file named `sample.ts` with the content below: + +```typescript +function bar(): void { +} +``` + +Hovering over `bar()` shows the following hover information in Visual Studio Code: + +--- + +![Hover over Bar](./hover.png) + +--- + +This hover information is expressed in LSP using the `Hover` type: + +```typescript +export interface Hover { + /** + * The hover's content + */ + contents: MarkupContent | MarkedString | MarkedString[]; + /** + * An optional range + */ + range?: Range; +} +``` + +In the above example, the concrete value is: + +```typescript +{ + contents: [ + { language: "typescript", value: "function bar(): void" } + ] +} +``` + +A client tool would retrieve the hover content from a language server by sending a `textDocument/hover` request for document `file:///Users/dirkb/sample.ts` at position `{line: 0, character: 10}`. + +LSIF defines a format that language servers or standalone tools emit to describe that the tuple `['textDocument/hover', 'file:///Users/dirkb/sample.ts', {line: 0, character: 10}]` resolves to the above hover. The data can then be taken and persisted into a database. + +LSP requests are position based, however results often only vary for ranges and not for single positions. In the above hover example, the hover value is the same for all positions of the identifier `bar`. This means the same hover value is returned when a user hovers over `b` in `bar` or over `r` in `bar`. To make the emitted data more compact, the LSIF uses ranges instead of positions. For this example, an LSIF tool emits the tuple `['textDocument/hover', 'file:///Users/dirkb/sample.ts', { start: { line: 0, character: 9 }, end: { line: 0, character: 12 }]` which includes range information. + +LSIF uses graphs to emit this information. In the graph, an LSP request is represented using an edge. Documents, ranges, or request results (for example, the hover) are represented using vertices. This format has the following benefits: + +- For a given code range, there can be different results. For a given identifier range, a user is interested in the hover value, the location of the definition, or to Find All References. LSIF therefore links these results with the range. +- Extending the format with additional request types or results can easily be done by adding new edge or vertex kinds. +- It is possible to emit data as soon as it is available. This enables streaming rather than having to store large amounts of data in memory. For example, emitting data for a document should be done for each file as the parsing progresses. + +For the hover example, the emitted LSIF graph data looks as follows: + +```typescript +// a vertex representing the document +{ id: 1, type: "vertex", label: "document", uri: "file:///Users/dirkb/sample.ts", languageId: "typescript" } +// a vertex representing the range for the identifier bar +{ id: 4, type: "vertex", label: "range", start: { line: 0, character: 9}, end: { line: 0, character: 12 } } +// an edge saying that the document with id 1 contains the range with id 4 +{ id: 5, type: "edge", label: "contains", outV: 1, inV: 4} +// a vertex representing the actual hover result +{ id: 6, type: "vertex", label: "hoverResult", + result: { + contents: [ + { language: "typescript", value: "function bar(): void" } + ] + } +} +// an edge linking the hover result to the range. +{ id: 7, type: "edge", label: "textDocument/hover", outV: 4, inV: 6 } +``` + +The corresponding graph looks like this: + +![LSIF graph for a hover](./hoverResult.png) + +The LSP also supports requests that only take a document as a parameter (they are not position based). Example requests that are useful for code comprehension are for a list of all document symbols or to compute all folding ranges. These requests are modeled in LSIF in the form `[request, document]` -> result. + +Let's look at another example: + +```typescript +function bar(): void { + console.log('Hello World!'); +} +``` + +The folding range result for the document containing above function `bar` is emitted like this: + +```typescript +// a vertex representing the document +{ id: 1, type: "vertex", label: "document", uri: "file:///Users/dirkb/sample.ts", languageId: "typescript" } +// a vertex representing the folding result +{ id: 2, type: "vertex", label: "foldingRangeResult", result: [ { startLine: 0, startCharacter: 20, endLine: 2, endCharacter: 1 } ] } +// an edge connecting the folding result to the document. +{ id: 3, type: "edge", label: "textDocument/foldingRange", outV: 1, inV: 2 } +``` + +![LSIF graph for a folding range result](./foldingRange.png) + +These are only two examples of LSP requests supported by the LSIF. The current version of the [LSIF specification](https://github.com/Microsoft/language-server-protocol/blob/master/indexFormat/specification.md) also supports document symbols, document links, Go to Definition, Go to Declaration, Go to Type Definition, Find All References, and Go to Implementation. + +## We need your feedback! + +We have made good initial progress on the LSIF specification and we want to open the conversation to the community so you can learn what we're working on. For feedback, please comment on the issue [Language Server Index Format](https://github.com/Microsoft/language-server-protocol/issues/623). + +## How to get started + +To get started with LSIF, you can have a look at the following resources: + +- The [LSIF specification](https://github.com/Microsoft/language-server-protocol/blob/master/indexFormat/specification.md) - The document also describes some additional optimizations that have been done to keep the emitted data compact. +- [LSIF Index for TypeScript](https://github.com/Microsoft/lsif-typescript) - A tool that generates LSIF for TypeScript. The README provides instructions for using the tool. +- [Visual Studio Code extension for LSIF](https://github.com/Microsoft/vscode-lsif-extension) - An extension for VS Code that provides language comprehension features using an LSIF JSON dump. If you implement a new LSIF generator, you can use this extension to validate it with arbitrary source code. \ No newline at end of file diff --git a/build/keybindings/doc.keybindings.linux.json b/build/keybindings/doc.keybindings.linux.json new file mode 100644 index 0000000000000000000000000000000000000000..10bd7dcea759c35d1dccade41544cc43b35d488b --- /dev/null +++ b/build/keybindings/doc.keybindings.linux.json @@ -0,0 +1,894 @@ +[ +{ "key": "escape escape", "command": "workbench.action.exitZenMode", + "when": "inZenMode" }, +{ "key": "shift+escape", "command": "closeReferenceSearchEditor", + "when": "inReferenceSearchEditor && !config.editor.stablePeek" }, +{ "key": "escape", "command": "closeReferenceSearchEditor", + "when": "inReferenceSearchEditor && !config.editor.stablePeek" }, +{ "key": "shift+escape", "command": "cancelSelection", + "when": "editorHasSelection && textInputFocus" }, +{ "key": "escape", "command": "cancelSelection", + "when": "editorHasSelection && textInputFocus" }, +{ "key": "ctrl+end", "command": "cursorBottom", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+end", "command": "cursorBottomSelect", + "when": "textInputFocus" }, +{ "key": "down", "command": "cursorDown", + "when": "textInputFocus" }, +{ "key": "shift+down", "command": "cursorDownSelect", + "when": "textInputFocus" }, +{ "key": "end", "command": "cursorEnd", + "when": "textInputFocus" }, +{ "key": "shift+end", "command": "cursorEndSelect", + "when": "textInputFocus" }, +{ "key": "home", "command": "cursorHome", + "when": "textInputFocus" }, +{ "key": "shift+home", "command": "cursorHomeSelect", + "when": "textInputFocus" }, +{ "key": "left", "command": "cursorLeft", + "when": "textInputFocus" }, +{ "key": "shift+left", "command": "cursorLeftSelect", + "when": "textInputFocus" }, +{ "key": "pagedown", "command": "cursorPageDown", + "when": "textInputFocus" }, +{ "key": "shift+pagedown", "command": "cursorPageDownSelect", + "when": "textInputFocus" }, +{ "key": "pageup", "command": "cursorPageUp", + "when": "textInputFocus" }, +{ "key": "shift+pageup", "command": "cursorPageUpSelect", + "when": "textInputFocus" }, +{ "key": "right", "command": "cursorRight", + "when": "textInputFocus" }, +{ "key": "shift+right", "command": "cursorRightSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+home", "command": "cursorTop", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+home", "command": "cursorTopSelect", + "when": "textInputFocus" }, +{ "key": "up", "command": "cursorUp", + "when": "textInputFocus" }, +{ "key": "shift+up", "command": "cursorUpSelect", + "when": "textInputFocus" }, +{ "key": "shift+backspace", "command": "deleteLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "backspace", "command": "deleteLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "delete", "command": "deleteRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+a", "command": "editor.action.selectAll", + "when": "textInputFocus" }, +{ "key": "ctrl+l", "command": "expandLineSelection", + "when": "textInputFocus" }, +{ "key": "shift+tab", "command": "outdent", + "when": "editorTextFocus && !editorReadonly && !editorTabMovesFocus" }, +{ "key": "ctrl+shift+z", "command": "redo", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+y", "command": "redo", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+down", "command": "scrollLineDown", + "when": "textInputFocus" }, +{ "key": "ctrl+up", "command": "scrollLineUp", + "when": "textInputFocus" }, +{ "key": "alt+pagedown", "command": "scrollPageDown", + "when": "textInputFocus" }, +{ "key": "alt+pageup", "command": "scrollPageUp", + "when": "textInputFocus" }, +{ "key": "tab", "command": "tab", + "when": "editorTextFocus && !editorReadonly && !editorTabMovesFocus" }, +{ "key": "ctrl+z", "command": "undo", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "shift+escape", "command": "removeSecondaryCursors", + "when": "editorHasMultipleSelections && textInputFocus" }, +{ "key": "escape", "command": "removeSecondaryCursors", + "when": "editorHasMultipleSelections && textInputFocus" }, +{ "key": "ctrl+f", "command": "actions.find" }, +{ "key": "enter", "command": "breakpointWidget.action.acceptInput", + "when": "breakpointWidgetVisible && inBreakpointWidget" }, +{ "key": "shift+escape", "command": "closeBreakpointWidget", + "when": "breakpointWidgetVisible && textInputFocus" }, +{ "key": "escape", "command": "closeBreakpointWidget", + "when": "breakpointWidgetVisible && textInputFocus" }, +{ "key": "shift+escape", "command": "closeReviewPanel", + "when": "reviewPanelVisible" }, +{ "key": "escape", "command": "closeReviewPanel", + "when": "reviewPanelVisible" }, +{ "key": "ctrl+u", "command": "cursorUndo", + "when": "textInputFocus" }, +{ "key": "ctrl+right", "command": "cursorWordEndRight", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+right", "command": "cursorWordEndRightSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+left", "command": "cursorWordStartLeft", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+left", "command": "cursorWordStartLeftSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+backspace", "command": "deleteWordLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+delete", "command": "deleteWordRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+k ctrl+c", "command": "editor.action.addCommentLine", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+d", "command": "editor.action.addSelectionToNextFindMatch", + "when": "editorFocus" }, +{ "key": "shift+alt+.", "command": "editor.action.autoFix", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+alt+<", "command": "editor.action.autoFix", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+a", "command": "editor.action.blockComment", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+f2", "command": "editor.action.changeAll", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+c", "command": "editor.action.clipboardCopyAction", + "when": "textInputFocus" }, +{ "key": "ctrl+x", "command": "editor.action.clipboardCutAction", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+v", "command": "editor.action.clipboardPasteAction", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+/", "command": "editor.action.commentLine", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+alt+down", "command": "editor.action.copyLinesDownAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+alt+up", "command": "editor.action.copyLinesUpAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+k ctrl+k", "command": "editor.action.defineKeybinding", + "when": "editorTextFocus && !editorReadonly && editorLangId == 'jsonc'" }, +{ "key": "ctrl+shift+k", "command": "editor.action.deleteLines", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "f7", "command": "editor.action.diffReview.next", + "when": "isInDiffEditor" }, +{ "key": "shift+f7", "command": "editor.action.diffReview.prev", + "when": "isInDiffEditor" }, +{ "key": "alt+f3", "command": "editor.action.dirtydiff.next", + "when": "editorTextFocus" }, +{ "key": "shift+alt+f3", "command": "editor.action.dirtydiff.previous", + "when": "editorTextFocus" }, +{ "key": "ctrl+f", "command": "editor.action.extensioneditor.showfind", + "when": "activeEditor == 'workbench.editor.extension'" }, +{ "key": "ctrl+shift+i", "command": "editor.action.formatDocument", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+k ctrl+f", "command": "editor.action.formatSelection", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+f12", "command": "editor.action.goToImplementation", + "when": "editorHasImplementationProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "ctrl+shift+.", "command": "editor.action.inPlaceReplace.down", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+<", "command": "editor.action.inPlaceReplace.down", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+,", "command": "editor.action.inPlaceReplace.up", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+<", "command": "editor.action.inPlaceReplace.up", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+]", "command": "editor.action.indentLines", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+up", "command": "editor.action.insertCursorAbove", + "when": "editorTextFocus" }, +{ "key": "shift+alt+up", "command": "editor.action.insertCursorAbove", + "when": "editorTextFocus" }, +{ "key": "shift+alt+i", "command": "editor.action.insertCursorAtEndOfEachLineSelected", + "when": "editorTextFocus" }, +{ "key": "ctrl+shift+down", "command": "editor.action.insertCursorBelow", + "when": "editorTextFocus" }, +{ "key": "shift+alt+down", "command": "editor.action.insertCursorBelow", + "when": "editorTextFocus" }, +{ "key": "ctrl+enter", "command": "editor.action.insertLineAfter", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+enter", "command": "editor.action.insertLineBefore", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+\\", "command": "editor.action.jumpToBracket", + "when": "editorTextFocus" }, +{ "key": "alt+f8", "command": "editor.action.marker.next", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "f8", "command": "editor.action.marker.nextInFiles", + "when": "editorFocus && !editorReadonly" }, +{ "key": "shift+alt+f8", "command": "editor.action.marker.prev", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+f8", "command": "editor.action.marker.prevInFiles", + "when": "editorFocus && !editorReadonly" }, +{ "key": "alt+down", "command": "editor.action.moveLinesDownAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "alt+up", "command": "editor.action.moveLinesUpAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+k ctrl+d", "command": "editor.action.moveSelectionToNextFindMatch", + "when": "editorFocus" }, +{ "key": "f3", "command": "editor.action.nextMatchFindAction", + "when": "editorFocus" }, +{ "key": "ctrl+f3", "command": "editor.action.nextSelectionMatchFindAction", + "when": "editorFocus" }, +{ "key": "shift+alt+o", "command": "editor.action.organizeImports", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+[", "command": "editor.action.outdentLines", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+f10", "command": "editor.action.peekDefinition", + "when": "editorHasDefinitionProvider && editorTextFocus && !inReferenceSearchEditor && !isInEmbeddedEditor" }, +{ "key": "ctrl+shift+f12", "command": "editor.action.peekImplementation", + "when": "editorHasImplementationProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "shift+f3", "command": "editor.action.previousMatchFindAction", + "when": "editorFocus" }, +{ "key": "ctrl+shift+f3", "command": "editor.action.previousSelectionMatchFindAction", + "when": "editorFocus" }, +{ "key": "ctrl+.", "command": "editor.action.quickFix", + "when": "editorHasCodeActionsProvider && editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+r", "command": "editor.action.refactor", + "when": "editorHasCodeActionsProvider && editorTextFocus && !editorReadonly" }, +{ "key": "shift+f12", "command": "editor.action.referenceSearch.trigger", + "when": "editorHasReferenceProvider && editorTextFocus && !inReferenceSearchEditor && !isInEmbeddedEditor" }, +{ "key": "ctrl+k ctrl+u", "command": "editor.action.removeCommentLine", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "f2", "command": "editor.action.rename", + "when": "editorHasRenameProvider && editorTextFocus && !editorReadonly" }, +{ "key": "f12", "command": "editor.action.revealDefinition", + "when": "editorHasDefinitionProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "ctrl+k f12", "command": "editor.action.revealDefinitionAside", + "when": "editorHasDefinitionProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "ctrl+shift+l", "command": "editor.action.selectHighlights", + "when": "editorFocus" }, +{ "key": "alt+f1", "command": "editor.action.showAccessibilityHelp", + "when": "editorFocus" }, +{ "key": "shift+f10", "command": "editor.action.showContextMenu", + "when": "textInputFocus" }, +{ "key": "ctrl+k ctrl+i", "command": "editor.action.showHover", + "when": "editorTextFocus" }, +{ "key": "shift+alt+right", "command": "editor.action.smartSelect.expand", + "when": "editorTextFocus" }, +{ "key": "shift+alt+left", "command": "editor.action.smartSelect.shrink", + "when": "editorTextFocus" }, +{ "key": "ctrl+h", "command": "editor.action.startFindReplaceAction" }, +{ "key": "ctrl+m", "command": "editor.action.toggleTabFocusMode" }, +{ "key": "alt+z", "command": "editor.action.toggleWordWrap" }, +{ "key": "ctrl+shift+space", "command": "editor.action.triggerParameterHints", + "when": "editorHasSignatureHelpProvider && editorTextFocus" }, +{ "key": "ctrl+space", "command": "editor.action.triggerSuggest", + "when": "editorHasCompletionItemProvider && textInputFocus && !editorReadonly" }, +{ "key": "ctrl+k ctrl+x", "command": "editor.action.trimTrailingWhitespace", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "escape", "command": "editor.action.webvieweditor.hideFind", + "when": "webviewFindWidgetVisible && !editorFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "escape", "command": "editor.action.webvieweditor.hideFind", + "when": "webviewFindWidgetVisible && !editorFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "ctrl+a", "command": "editor.action.webvieweditor.selectAll", + "when": "!editorFocus && !inputFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "ctrl+a", "command": "editor.action.webvieweditor.selectAll", + "when": "!editorFocus && !inputFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "ctrl+f", "command": "editor.action.webvieweditor.showFind", + "when": "!editorFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "ctrl+f", "command": "editor.action.webvieweditor.showFind", + "when": "!editorFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "f7", "command": "editor.action.wordHighlight.next", + "when": "editorTextFocus && hasWordHighlights" }, +{ "key": "shift+f7", "command": "editor.action.wordHighlight.prev", + "when": "editorTextFocus && hasWordHighlights" }, +{ "key": "ctrl+k ctrl+i", "command": "editor.debug.action.showDebugHover", + "when": "editorTextFocus && inDebugMode" }, +{ "key": "f9", "command": "editor.debug.action.toggleBreakpoint", + "when": "editorTextFocus" }, +{ "key": "tab", "command": "editor.emmet.action.expandAbbreviation", + "when": "config.emmet.triggerExpansionOnTab && editorTextFocus && !editorReadonly && !editorTabMovesFocus" }, +{ "key": "ctrl+shift+[", "command": "editor.fold", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+0", "command": "editor.foldAll", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+/", "command": "editor.foldAllBlockComments", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+8", "command": "editor.foldAllMarkerRegions", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+1", "command": "editor.foldLevel1", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+2", "command": "editor.foldLevel2", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+3", "command": "editor.foldLevel3", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+4", "command": "editor.foldLevel4", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+5", "command": "editor.foldLevel5", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+6", "command": "editor.foldLevel6", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+7", "command": "editor.foldLevel7", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+[", "command": "editor.foldRecursively", + "when": "editorTextFocus" }, +{ "key": "ctrl+shift+]", "command": "editor.unfold", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+j", "command": "editor.unfoldAll", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+9", "command": "editor.unfoldAllMarkerRegions", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+]", "command": "editor.unfoldRecursively", + "when": "editorTextFocus" }, +{ "key": "tab", "command": "insertSnippet", + "when": "editorTextFocus && hasSnippetCompletions && !editorTabMovesFocus && !inSnippetMode" }, +{ "key": "ctrl+enter", "command": "openReferenceToSide", + "when": "referenceSearchTreeFocused && referenceSearchVisible" }, +{ "key": "enter", "command": "repl.action.acceptInput", + "when": "inDebugRepl && textInputFocus" }, +{ "key": "escape", "command": "settings.action.clearSearchResults", + "when": "inSettingsSearch" }, +{ "key": "ctrl+.", "command": "settings.action.editFocusedSetting", + "when": "inSettingsSearch" }, +{ "key": "enter", "command": "settings.action.focusNextSetting", + "when": "inSettingsSearch" }, +{ "key": "shift+enter", "command": "settings.action.focusPreviousSetting", + "when": "inSettingsSearch" }, +{ "key": "down", "command": "settings.action.focusSettingsFile", + "when": "inSettingsSearch && !suggestWidgetVisible" }, +{ "key": "ctrl+f", "command": "settings.action.search", + "when": "inSettingsEditor" }, +{ "key": "alt+f5", "command": "workbench.action.editor.nextChange", + "when": "editorTextFocus" }, +{ "key": "shift+alt+f5", "command": "workbench.action.editor.previousChange", + "when": "editorTextFocus" }, +{ "key": "shift+escape", "command": "closeFindWidget", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "escape", "command": "closeFindWidget", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "ctrl+alt+enter", "command": "editor.action.replaceAll", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "ctrl+shift+1", "command": "editor.action.replaceOne", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "alt+enter", "command": "editor.action.selectAllMatches", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "alt+c", "command": "toggleFindCaseSensitive", + "when": "editorFocus" }, +{ "key": "alt+l", "command": "toggleFindInSelection", + "when": "editorFocus" }, +{ "key": "alt+r", "command": "toggleFindRegex", + "when": "editorFocus" }, +{ "key": "alt+w", "command": "toggleFindWholeWord", + "when": "editorFocus" }, +{ "key": "tab", "command": "jumpToNextSnippetPlaceholder", + "when": "editorTextFocus && hasNextTabstop && inSnippetMode" }, +{ "key": "shift+tab", "command": "jumpToPrevSnippetPlaceholder", + "when": "editorTextFocus && hasPrevTabstop && inSnippetMode" }, +{ "key": "escape", "command": "leaveEditorMessage", + "when": "messageVisible" }, +{ "key": "shift+escape", "command": "leaveSnippet", + "when": "editorTextFocus && inSnippetMode" }, +{ "key": "escape", "command": "leaveSnippet", + "when": "editorTextFocus && inSnippetMode" }, +{ "key": "shift+escape", "command": "closeDirtyDiff", + "when": "dirtyDiffVisible" }, +{ "key": "escape", "command": "closeDirtyDiff", + "when": "dirtyDiffVisible" }, +{ "key": "shift+escape", "command": "closeMarkersNavigation", + "when": "editorFocus && markersNavigationVisible" }, +{ "key": "escape", "command": "closeMarkersNavigation", + "when": "editorFocus && markersNavigationVisible" }, +{ "key": "f4", "command": "goToNextReferenceFromEmbeddedEditor", + "when": "inReferenceSearchEditor" }, +{ "key": "shift+f4", "command": "goToPreviousReferenceFromEmbeddedEditor", + "when": "inReferenceSearchEditor" }, +{ "key": "shift+escape", "command": "closeParameterHints", + "when": "editorFocus && parameterHintsVisible" }, +{ "key": "escape", "command": "closeParameterHints", + "when": "editorFocus && parameterHintsVisible" }, +{ "key": "alt+down", "command": "showNextParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "down", "command": "showNextParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "alt+up", "command": "showPrevParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "up", "command": "showPrevParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "tab", "command": "acceptSelectedSuggestion", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "enter", "command": "acceptSelectedSuggestionOnEnter", + "when": "acceptSuggestionOnEnter && suggestWidgetVisible && suggestionMakesTextEdit && textInputFocus" }, +{ "key": "shift+escape", "command": "hideSuggestWidget", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "escape", "command": "hideSuggestWidget", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "tab", "command": "insertBestCompletion", + "when": "atEndOfWord && !hasOtherSuggestions && !inSnippetMode && !suggestWidgetVisible && config.editor.tabCompletion == 'on'" }, +{ "key": "tab", "command": "insertNextSuggestion", + "when": "hasOtherSuggestions && textInputFocus && !inSnippetMode && !suggestWidgetVisible && config.editor.tabCompletion == 'on'" }, +{ "key": "shift+tab", "command": "insertPrevSuggestion", + "when": "hasOtherSuggestions && textInputFocus && !inSnippetMode && !suggestWidgetVisible && config.editor.tabCompletion == 'on'" }, +{ "key": "ctrl+pagedown", "command": "selectNextPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "pagedown", "command": "selectNextPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+down", "command": "selectNextSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "down", "command": "selectNextSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+pageup", "command": "selectPrevPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "pageup", "command": "selectPrevPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+up", "command": "selectPrevSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "up", "command": "selectPrevSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+space", "command": "toggleSuggestionDetails", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+alt+space", "command": "toggleSuggestionFocus", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "enter", "command": "acceptRenameInput", + "when": "editorFocus && renameInputVisible" }, +{ "key": "shift+escape", "command": "cancelRenameInput", + "when": "editorFocus && renameInputVisible" }, +{ "key": "escape", "command": "cancelRenameInput", + "when": "editorFocus && renameInputVisible" }, +{ "key": "ctrl+shift+;", "command": "breadcrumbs.focus", + "when": "breadcrumbsPossible" }, +{ "key": "ctrl+shift+.", "command": "breadcrumbs.focusAndSelect", + "when": "breadcrumbsPossible" }, +{ "key": "ctrl+shift+<", "command": "breadcrumbs.focusAndSelect", + "when": "breadcrumbsPossible" }, +{ "key": "ctrl+right", "command": "breadcrumbs.focusNext", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "right", "command": "breadcrumbs.focusNext", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "ctrl+left", "command": "breadcrumbs.focusPrevious", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "left", "command": "breadcrumbs.focusPrevious", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "ctrl+enter", "command": "breadcrumbs.revealFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "space", "command": "breadcrumbs.revealFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "ctrl+enter", "command": "breadcrumbs.revealFocusedFromTreeAside", + "when": "breadcrumbsActive && breadcrumbsVisible && listFocus && !inputFocus" }, +{ "key": "down", "command": "breadcrumbs.selectFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "enter", "command": "breadcrumbs.selectFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "ctrl+shift+.", "command": "breadcrumbs.toggleToOn", + "when": "!config.breadcrumbs.enabled" }, +{ "key": "ctrl+shift+<", "command": "breadcrumbs.toggleToOn", + "when": "!config.breadcrumbs.enabled" }, +{ "key": "shift+escape", "command": "closeAccessibilityHelp", + "when": "accessibilityHelpWidgetVisible && editorFocus" }, +{ "key": "escape", "command": "closeAccessibilityHelp", + "when": "accessibilityHelpWidgetVisible && editorFocus" }, +{ "key": "escape", "command": "closeReplaceInFilesWidget", + "when": "replaceInputBoxFocus && searchViewletVisible" }, +{ "key": "ctrl+alt+c", "command": "copyFilePath", + "when": "!editorFocus" }, +{ "key": "ctrl+shift+alt+c", "command": "copyRelativeFilePath", + "when": "!editorFocus" }, +{ "key": "alt+enter", "command": "debug.openBreakpointToSide", + "when": "breakpointsFocused" }, +{ "key": "ctrl+enter", "command": "debug.openBreakpointToSide", + "when": "breakpointsFocused" }, +{ "key": "delete", "command": "debug.removeBreakpoint", + "when": "breakpointsFocused && !breakpointSelected" }, +{ "key": "delete", "command": "debug.removeWatchExpression", + "when": "watchExpressionsFocused && !expressionSelected" }, +{ "key": "shift+f9", "command": "editor.debug.action.toggleInlineBreakpoint", + "when": "editorTextFocus" }, +{ "key": "ctrl+enter", "command": "explorer.openToSide", + "when": "explorerViewletFocus && explorerViewletVisible && !inputFocus" }, +{ "key": "shift+alt+f", "command": "filesExplorer.findInFolder", + "when": "explorerResourceIsFolder && explorerViewletVisible && filesExplorerFocus && !inputFocus && resourceScheme == 'file'" }, +{ "key": "alt+down", "command": "history.showNext", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "down", "command": "history.showNext", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "alt+up", "command": "history.showPrevious", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "ctrl+c", "command": "problems.action.copy", + "when": "problemFocus" }, +{ "key": "ctrl+f", "command": "problems.action.focusFilter", + "when": "problemsViewFocus" }, +{ "key": "ctrl+down", "command": "problems.action.focusProblemsFromFilter", + "when": "problemsFilterFocus" }, +{ "key": "up", "command": "history.showPrevious", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "escape", "command": "keybindings.editor.clearSearchResults", + "when": "inKeybindings && inKeybindingsSearch" }, +{ "key": "ctrl+c", "command": "keybindings.editor.copyKeybindingEntry", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "ctrl+k ctrl+k", "command": "keybindings.editor.defineKeybinding", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "ctrl+k ctrl+e", "command": "keybindings.editor.defineWhenExpression", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "down", "command": "keybindings.editor.focusKeybindings", + "when": "inKeybindings && inKeybindingsSearch" }, +{ "key": "alt+k", "command": "keybindings.editor.recordSearchKeys", + "when": "inKeybindings && inKeybindingsSearch" }, +{ "key": "delete", "command": "keybindings.editor.removeKeybinding", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "ctrl+f", "command": "keybindings.editor.searchKeybindings", + "when": "inKeybindings" }, +{ "key": "alt+p", "command": "keybindings.editor.toggleSortByPrecedence", + "when": "inKeybindings" }, +{ "key": "escape", "command": "list.clear", + "when": "listFocus && listHasSelectionOrFocus && !inputFocus" }, +{ "key": "left", "command": "list.collapse", + "when": "listFocus && !inputFocus" }, +{ "key": "right", "command": "list.expand", + "when": "listFocus && !inputFocus" }, +{ "key": "shift+down", "command": "list.expandSelectionDown", + "when": "listFocus && listSupportsMultiselect && !inputFocus" }, +{ "key": "shift+up", "command": "list.expandSelectionUp", + "when": "listFocus && listSupportsMultiselect && !inputFocus" }, +{ "key": "down", "command": "list.focusDown", + "when": "listFocus && !inputFocus" }, +{ "key": "home", "command": "list.focusFirst", + "when": "listFocus && !inputFocus" }, +{ "key": "end", "command": "list.focusLast", + "when": "listFocus && !inputFocus" }, +{ "key": "pagedown", "command": "list.focusPageDown", + "when": "listFocus && !inputFocus" }, +{ "key": "pageup", "command": "list.focusPageUp", + "when": "listFocus && !inputFocus" }, +{ "key": "up", "command": "list.focusUp", + "when": "listFocus && !inputFocus" }, +{ "key": "enter", "command": "list.select", + "when": "listFocus && !inputFocus" }, +{ "key": "ctrl+a", "command": "list.selectAll", + "when": "listFocus && listSupportsMultiselect && !inputFocus" }, +{ "key": "space", "command": "list.toggleExpand", + "when": "listFocus && !inputFocus" }, +{ "key": "delete", "command": "notification.clear", + "when": "notificationFocus" }, +{ "key": "left", "command": "notification.collapse", + "when": "notificationFocus" }, +{ "key": "right", "command": "notification.expand", + "when": "notificationFocus" }, +{ "key": "enter", "command": "notification.toggle", + "when": "notificationFocus" }, +{ "key": "space", "command": "notification.toggle", + "when": "notificationFocus" }, +{ "key": "home", "command": "notifications.focusFirstToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "pageup", "command": "notifications.focusFirstToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "end", "command": "notifications.focusLastToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "pagedown", "command": "notifications.focusLastToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "down", "command": "notifications.focusNextToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "up", "command": "notifications.focusPreviousToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "ctrl+enter", "command": "problems.action.openToSide", + "when": "problemFocus" }, +{ "key": "ctrl+.", "command": "problems.action.showQuickFixes", + "when": "problemFocus" }, +{ "key": "ctrl+alt+r", "command": "revealFileInOS", + "when": "!editorFocus" }, +{ "key": "ctrl+enter", "command": "scm.acceptInput", + "when": "scmRepository" }, +{ "key": "escape", "command": "search.action.cancel", + "when": "listFocus && searchViewletVisible && !inputFocus" }, +{ "key": "ctrl+c", "command": "search.action.copyMatch", + "when": "fileMatchOrMatchFocus" }, +{ "key": "ctrl+alt+c", "command": "search.action.copyPath", + "when": "fileMatchOrFolderMatchFocus" }, +{ "key": "f4", "command": "search.action.focusNextSearchResult", + "when": "hasSearchResult" }, +{ "key": "shift+f4", "command": "search.action.focusPreviousSearchResult", + "when": "hasSearchResult" }, +{ "key": "ctrl+up", "command": "search.action.focusSearchFromResults", + "when": "firstMatchFocus && searchViewletVisible" }, +{ "key": "ctrl+enter", "command": "search.action.openResultToSide", + "when": "fileMatchOrMatchFocus && searchViewletVisible" }, +{ "key": "delete", "command": "search.action.remove", + "when": "fileMatchOrMatchFocus && searchViewletVisible" }, +{ "key": "ctrl+shift+1", "command": "search.action.replace", + "when": "matchFocus && replaceActive && searchViewletVisible" }, +{ "key": "ctrl+alt+enter", "command": "search.action.replaceAll", + "when": "replaceActive && searchViewletVisible && !findWidgetVisible" }, +{ "key": "ctrl+shift+enter", "command": "search.action.replaceAllInFile", + "when": "fileMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "ctrl+shift+1", "command": "search.action.replaceAllInFile", + "when": "fileMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "ctrl+shift+enter", "command": "search.action.replaceAllInFolder", + "when": "folderMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "ctrl+shift+1", "command": "search.action.replaceAllInFolder", + "when": "folderMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "ctrl+down", "command": "search.focus.nextInputBox", + "when": "inputBoxFocus && searchViewletVisible" }, +{ "key": "ctrl+up", "command": "search.focus.previousInputBox", + "when": "inputBoxFocus && searchViewletVisible && !searchInputBoxFocus" }, +{ "key": "down", "command": "settings.action.focusSettingsFromSearch", + "when": "inSettingsSearch && !suggestWidgetVisible" }, +{ "key": "enter", "command": "settings.action.focusSettingsList", + "when": "inSettingsEditor && settingsTocRowFocus" }, +{ "key": "shift+f9", "command": "settings.action.showContextMenu", + "when": "inSettingsEditor" }, +{ "key": "alt+c", "command": "toggleSearchCaseSensitive", + "when": "searchViewletFocus && searchViewletVisible && !fileMatchOrFolderMatchFocus" }, +{ "key": "alt+r", "command": "toggleSearchRegex", + "when": "searchViewletFocus && searchViewletVisible" }, +{ "key": "alt+w", "command": "toggleSearchWholeWord", + "when": "searchViewletFocus && searchViewletVisible" }, +{ "key": "ctrl+w", "command": "workbench.action.closeActiveEditor" }, +{ "key": "ctrl+k ctrl+w", "command": "workbench.action.closeAllEditors" }, +{ "key": "ctrl+k ctrl+shift+w", "command": "workbench.action.closeAllGroups" }, +{ "key": "ctrl+k w", "command": "workbench.action.closeEditorsInGroup" }, +{ "key": "ctrl+k f", "command": "workbench.action.closeFolder" }, +{ "key": "ctrl+w", "command": "workbench.action.closeGroup", + "when": "activeEditorGroupEmpty && multipleEditorGroups" }, +{ "key": "shift+escape", "command": "workbench.action.closeQuickOpen", + "when": "inQuickOpen" }, +{ "key": "escape", "command": "workbench.action.closeQuickOpen", + "when": "inQuickOpen" }, +{ "key": "ctrl+k u", "command": "workbench.action.closeUnmodifiedEditors" }, +{ "key": "ctrl+shift+w", "command": "workbench.action.closeWindow" }, +{ "key": "ctrl+w", "command": "workbench.action.closeWindow", + "when": "!editorIsOpen && !multipleEditorGroups" }, +{ "key": "alt+f5", "command": "workbench.action.compareEditor.nextChange", + "when": "textCompareEditorVisible" }, +{ "key": "shift+alt+f5", "command": "workbench.action.compareEditor.previousChange", + "when": "textCompareEditorVisible" }, +{ "key": "f5", "command": "workbench.action.debug.continue", + "when": "inDebugMode" }, +{ "key": "f6", "command": "workbench.action.debug.pause", + "when": "inDebugMode" }, +{ "key": "ctrl+shift+f5", "command": "workbench.action.debug.restart", + "when": "inDebugMode" }, +{ "key": "ctrl+f5", "command": "workbench.action.debug.run", + "when": "!inDebugMode" }, +{ "key": "f5", "command": "workbench.action.debug.start", + "when": "!inDebugMode" }, +{ "key": "shift+f11", "command": "workbench.action.debug.stepOut", + "when": "inDebugMode" }, +{ "key": "f10", "command": "workbench.action.debug.stepOver", + "when": "inDebugMode" }, +{ "key": "shift+f5", "command": "workbench.action.debug.stop", + "when": "inDebugMode" }, +{ "key": "ctrl+k m", "command": "workbench.action.editor.changeLanguageMode" }, +{ "key": "ctrl+k p", "command": "workbench.action.files.copyPathOfActiveFile" }, +{ "key": "ctrl+n", "command": "workbench.action.files.newUntitledFile" }, +{ "key": "ctrl+o", "command": "workbench.action.files.openFile" }, +{ "key": "ctrl+k ctrl+o", "command": "workbench.action.files.openFolder" }, +{ "key": "ctrl+k r", "command": "workbench.action.files.revealActiveFileInWindows" }, +{ "key": "ctrl+s", "command": "workbench.action.files.save" }, +{ "key": "ctrl+shift+s", "command": "workbench.action.files.saveAs" }, +{ "key": "ctrl+k s", "command": "workbench.action.files.saveWithoutFormatting" }, +{ "key": "ctrl+k o", "command": "workbench.action.files.showOpenedFileInNewWindow" }, +{ "key": "ctrl+shift+f", "command": "workbench.action.findInFiles" }, +{ "key": "ctrl+k ctrl+up", "command": "workbench.action.focusAboveGroup" }, +{ "key": "ctrl+k ctrl+down", "command": "workbench.action.focusBelowGroup" }, +{ "key": "ctrl+8", "command": "workbench.action.focusEighthEditorGroup" }, +{ "key": "ctrl+5", "command": "workbench.action.focusFifthEditorGroup" }, +{ "key": "ctrl+1", "command": "workbench.action.focusFirstEditorGroup" }, +{ "key": "ctrl+4", "command": "workbench.action.focusFourthEditorGroup" }, +{ "key": "ctrl+k ctrl+left", "command": "workbench.action.focusLeftGroup" }, +{ "key": "ctrl+k ctrl+right", "command": "workbench.action.focusRightGroup" }, +{ "key": "ctrl+2", "command": "workbench.action.focusSecondEditorGroup" }, +{ "key": "ctrl+7", "command": "workbench.action.focusSeventhEditorGroup" }, +{ "key": "ctrl+0", "command": "workbench.action.focusSideBar" }, +{ "key": "ctrl+6", "command": "workbench.action.focusSixthEditorGroup" }, +{ "key": "ctrl+3", "command": "workbench.action.focusThirdEditorGroup" }, +{ "key": "ctrl+g", "command": "workbench.action.gotoLine" }, +{ "key": "ctrl+shift+o", "command": "workbench.action.gotoSymbol" }, +{ "key": "escape", "command": "workbench.action.hideInterfaceOverview", + "when": "interfaceOverviewVisible" }, +{ "key": "down", "command": "workbench.action.interactivePlayground.arrowDown", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "up", "command": "workbench.action.interactivePlayground.arrowUp", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "pagedown", "command": "workbench.action.interactivePlayground.pageDown", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "pageup", "command": "workbench.action.interactivePlayground.pageUp", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "ctrl+k enter", "command": "workbench.action.keepEditor" }, +{ "key": "ctrl+k ctrl+r", "command": "workbench.action.keybindingsReference" }, +{ "key": "ctrl+9", "command": "workbench.action.lastEditorInGroup" }, +{ "key": "alt+0", "command": "workbench.action.lastEditorInGroup" }, +{ "key": "ctrl+k down", "command": "workbench.action.moveActiveEditorGroupDown" }, +{ "key": "ctrl+k left", "command": "workbench.action.moveActiveEditorGroupLeft" }, +{ "key": "ctrl+k right", "command": "workbench.action.moveActiveEditorGroupRight" }, +{ "key": "ctrl+k up", "command": "workbench.action.moveActiveEditorGroupUp" }, +{ "key": "ctrl+shift+pageup", "command": "workbench.action.moveEditorLeftInGroup" }, +{ "key": "ctrl+shift+pagedown", "command": "workbench.action.moveEditorRightInGroup" }, +{ "key": "shift+alt+1", "command": "workbench.action.moveEditorToFirstGroup" }, +{ "key": "shift+alt+9", "command": "workbench.action.moveEditorToLastGroup" }, +{ "key": "ctrl+alt+right", "command": "workbench.action.moveEditorToNextGroup" }, +{ "key": "ctrl+alt+left", "command": "workbench.action.moveEditorToPreviousGroup" }, +{ "key": "ctrl+alt+-", "command": "workbench.action.navigateBack" }, +{ "key": "ctrl+shift+-", "command": "workbench.action.navigateForward" }, +{ "key": "ctrl+k ctrl+q", "command": "workbench.action.navigateToLastEditLocation" }, +{ "key": "ctrl+shift+n", "command": "workbench.action.newWindow" }, +{ "key": "ctrl+pagedown", "command": "workbench.action.nextEditor" }, +{ "key": "alt+1", "command": "workbench.action.openEditorAtIndex1" }, +{ "key": "alt+2", "command": "workbench.action.openEditorAtIndex2" }, +{ "key": "alt+3", "command": "workbench.action.openEditorAtIndex3" }, +{ "key": "alt+4", "command": "workbench.action.openEditorAtIndex4" }, +{ "key": "alt+5", "command": "workbench.action.openEditorAtIndex5" }, +{ "key": "alt+6", "command": "workbench.action.openEditorAtIndex6" }, +{ "key": "alt+7", "command": "workbench.action.openEditorAtIndex7" }, +{ "key": "alt+8", "command": "workbench.action.openEditorAtIndex8" }, +{ "key": "alt+9", "command": "workbench.action.openEditorAtIndex9" }, +{ "key": "ctrl+k ctrl+s", "command": "workbench.action.openGlobalKeybindings" }, +{ "key": "ctrl+tab", "command": "workbench.action.openNextRecentlyUsedEditorInGroup" }, +{ "key": "ctrl+shift+tab", "command": "workbench.action.openPreviousRecentlyUsedEditorInGroup" }, +{ "key": "ctrl+r", "command": "workbench.action.openRecent" }, +{ "key": "ctrl+,", "command": "workbench.action.openSettings" }, +{ "key": "ctrl+k ctrl+h", "command": "workbench.action.output.toggleOutput" }, +{ "key": "ctrl+pageup", "command": "workbench.action.previousEditor" }, +{ "key": "ctrl+e", "command": "workbench.action.quickOpen" }, +{ "key": "ctrl+p", "command": "workbench.action.quickOpen" }, +{ "key": "ctrl+q", "command": "workbench.action.quit" }, +{ "key": "ctrl+shift+t", "command": "workbench.action.reopenClosedEditor" }, +{ "key": "ctrl+shift+h", "command": "workbench.action.replaceInFiles" }, +{ "key": "ctrl+shift+j", "command": "workbench.action.search.toggleQueryDetails", + "when": "searchViewletVisible" }, +{ "key": "ctrl+k ctrl+t", "command": "workbench.action.selectTheme" }, +{ "key": "ctrl+k ctrl+p", "command": "workbench.action.showAllEditors" }, +{ "key": "ctrl+t", "command": "workbench.action.showAllSymbols" }, +{ "key": "f1", "command": "workbench.action.showCommands" }, +{ "key": "ctrl+shift+p", "command": "workbench.action.showCommands" }, +{ "key": "ctrl+\\", "command": "workbench.action.splitEditor" }, +{ "key": "ctrl+k ctrl+\\", "command": "workbench.action.splitEditorOrthogonal" }, +{ "key": "ctrl+shift+b", "command": "workbench.action.tasks.build" }, +{ "key": "escape", "command": "workbench.action.terminal.clearSelection", + "when": "terminalFocus && terminalTextSelected && !terminalFindWidgetVisible" }, +{ "key": "ctrl+shift+c", "command": "workbench.action.terminal.copySelection", + "when": "terminalFocus && terminalTextSelected" }, +{ "key": "ctrl+backspace", "command": "workbench.action.terminal.deleteWordLeft", + "when": "terminalFocus" }, +{ "key": "ctrl+delete", "command": "workbench.action.terminal.deleteWordRight", + "when": "terminalFocus" }, +{ "key": "f3", "command": "workbench.action.terminal.findNext", + "when": "terminalFindWidgetFocused" }, +{ "key": "f3", "command": "workbench.action.terminal.findNextTerminalFocus", + "when": "terminalFocus" }, +{ "key": "shift+f3", "command": "workbench.action.terminal.findPrevious", + "when": "terminalFindWidgetFocused" }, +{ "key": "shift+f3", "command": "workbench.action.terminal.findPreviousTerminalFocus", + "when": "terminalFocus" }, +{ "key": "ctrl+f", "command": "workbench.action.terminal.focusFindWidget", + "when": "terminalFindWidgetFocused" }, +{ "key": "ctrl+f", "command": "workbench.action.terminal.focusFindWidget", + "when": "terminalFocus" }, +{ "key": "alt+down", "command": "workbench.action.terminal.focusNextPane", + "when": "terminalFocus" }, +{ "key": "alt+right", "command": "workbench.action.terminal.focusNextPane", + "when": "terminalFocus" }, +{ "key": "alt+up", "command": "workbench.action.terminal.focusPreviousPane", + "when": "terminalFocus" }, +{ "key": "alt+left", "command": "workbench.action.terminal.focusPreviousPane", + "when": "terminalFocus" }, +{ "key": "shift+escape", "command": "workbench.action.terminal.hideFindWidget", + "when": "terminalFindWidgetVisible && terminalFocus" }, +{ "key": "escape", "command": "workbench.action.terminal.hideFindWidget", + "when": "terminalFindWidgetVisible && terminalFocus" }, +{ "key": "ctrl+shift+`", "command": "workbench.action.terminal.new" }, +{ "key": "ctrl+shift+c", "command": "workbench.action.terminal.openNativeConsole", + "when": "!terminalFocus" }, +{ "key": "ctrl+shift+v", "command": "workbench.action.terminal.paste", + "when": "terminalFocus" }, +{ "key": "ctrl+shift+down", "command": "workbench.action.terminal.resizePaneDown", + "when": "terminalFocus" }, +{ "key": "ctrl+shift+left", "command": "workbench.action.terminal.resizePaneLeft", + "when": "terminalFocus" }, +{ "key": "ctrl+shift+right", "command": "workbench.action.terminal.resizePaneRight", + "when": "terminalFocus" }, +{ "key": "ctrl+shift+up", "command": "workbench.action.terminal.resizePaneUp", + "when": "terminalFocus" }, +{ "key": "ctrl+shift+down", "command": "workbench.action.terminal.scrollDown", + "when": "terminalFocus" }, +{ "key": "shift+pagedown", "command": "workbench.action.terminal.scrollDownPage", + "when": "terminalFocus" }, +{ "key": "shift+end", "command": "workbench.action.terminal.scrollToBottom", + "when": "terminalFocus" }, +{ "key": "shift+home", "command": "workbench.action.terminal.scrollToTop", + "when": "terminalFocus" }, +{ "key": "ctrl+shift+up", "command": "workbench.action.terminal.scrollUp", + "when": "terminalFocus" }, +{ "key": "shift+pageup", "command": "workbench.action.terminal.scrollUpPage", + "when": "terminalFocus" }, +{ "key": "ctrl+shift+5", "command": "workbench.action.terminal.split", + "when": "terminalFocus" }, +{ "key": "ctrl+\\", "command": "workbench.action.terminal.split", + "when": "terminalFocus" }, +{ "key": "alt+c", "command": "workbench.action.terminal.toggleFindCaseSensitive", + "when": "terminalFindWidgetFocused" }, +{ "key": "alt+c", "command": "workbench.action.terminal.toggleFindCaseSensitiveTerminalFocus", + "when": "terminalFocus" }, +{ "key": "alt+r", "command": "workbench.action.terminal.toggleFindRegex", + "when": "terminalFindWidgetFocused" }, +{ "key": "alt+r", "command": "workbench.action.terminal.toggleFindRegexTerminalFocus", + "when": "terminalFocus" }, +{ "key": "alt+w", "command": "workbench.action.terminal.toggleFindWholeWord", + "when": "terminalFindWidgetFocused" }, +{ "key": "alt+w", "command": "workbench.action.terminal.toggleFindWholeWordTerminalFocus", + "when": "terminalFocus" }, +{ "key": "ctrl+`", "command": "workbench.action.terminal.toggleTerminal" }, +{ "key": "shift+alt+0", "command": "workbench.action.toggleEditorGroupLayout" }, +{ "key": "f11", "command": "workbench.action.toggleFullScreen" }, +{ "key": "ctrl+j", "command": "workbench.action.togglePanel" }, +{ "key": "ctrl+b", "command": "workbench.action.toggleSidebarVisibility" }, +{ "key": "ctrl+meta+w", "command": "workbench.action.toggleTabsVisibility" }, +{ "key": "ctrl+k z", "command": "workbench.action.toggleZenMode" }, +{ "key": "ctrl+numpad_add", "command": "workbench.action.zoomIn" }, +{ "key": "ctrl+shift+=", "command": "workbench.action.zoomIn" }, +{ "key": "ctrl+=", "command": "workbench.action.zoomIn" }, +{ "key": "ctrl+numpad_subtract", "command": "workbench.action.zoomOut" }, +{ "key": "ctrl+-", "command": "workbench.action.zoomOut" }, +{ "key": "ctrl+numpad0", "command": "workbench.action.zoomReset" }, +{ "key": "ctrl+shift+m", "command": "workbench.actions.view.problems" }, +{ "key": "ctrl+shift+y", "command": "workbench.debug.action.toggleRepl" }, +{ "key": "ctrl+k ctrl+m", "command": "workbench.extensions.action.showRecommendedKeymapExtensions" }, +{ "key": "ctrl+k c", "command": "workbench.files.action.compareWithClipboard" }, +{ "key": "ctrl+k d", "command": "workbench.files.action.compareWithSaved" }, +{ "key": "ctrl+k e", "command": "workbench.files.action.focusOpenEditorsView", + "when": "workbench.explorer.openEditorsView.active" }, +{ "key": "ctrl+shift+d", "command": "workbench.view.debug" }, +{ "key": "ctrl+shift+e", "command": "workbench.view.explorer" }, +{ "key": "ctrl+shift+x", "command": "workbench.view.extensions" }, +{ "key": "ctrl+shift+g", "command": "workbench.view.scm" }, +{ "key": "ctrl+shift+f", "command": "workbench.view.search", + "when": "!searchViewletVisible" }, +{ "key": "escape", "command": "breadcrumbs.selectEditor", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "f11", "command": "workbench.action.debug.stepInto", + "when": "inDebugMode" }, +{ "key": "f2", "command": "debug.renameWatchExpression", + "when": "watchExpressionsFocused" }, +{ "key": "f2", "command": "debug.setVariable", + "when": "variablesFocused" }, +{ "key": "space", "command": "debug.toggleBreakpoint", + "when": "breakpointsFocused && !inputFocus" }, +{ "key": "delete", "command": "deleteFile", + "when": "explorerViewletVisible && filesExplorerFocus && !config.files.enableTrash && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "shift+delete", "command": "deleteFile", + "when": "config.files.enableTrash && explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "escape", "command": "filesExplorer.cancelCut", + "when": "explorerResourceCut && explorerViewletVisible && filesExplorerFocus && !inputFocus" }, +{ "key": "ctrl+c", "command": "filesExplorer.copy", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !inputFocus" }, +{ "key": "ctrl+x", "command": "filesExplorer.cut", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !inputFocus" }, +{ "key": "ctrl+v", "command": "filesExplorer.paste", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceReadonly && !inputFocus" }, +{ "key": "delete", "command": "moveFileToTrash", + "when": "config.files.enableTrash && explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "f2", "command": "renameFile", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "shift+escape", "command": "closeReferenceSearch", + "when": "referenceSearchVisible && !config.editor.stablePeek" }, +{ "key": "escape", "command": "closeReferenceSearch", + "when": "referenceSearchVisible && !config.editor.stablePeek" }, +{ "key": "f4", "command": "goToNextReference", + "when": "referenceSearchVisible" }, +{ "key": "shift+f4", "command": "goToPreviousReference", + "when": "referenceSearchVisible" }, +{ "key": "escape", "command": "notifications.hideList", + "when": "notificationCenterVisible" }, +{ "key": "escape", "command": "notifications.hideToasts", + "when": "notificationToastsVisible" }, +{ "key": "ctrl+alt+-", "command": "workbench.action.quickInputBack", + "when": "inQuickOpen" }, +{ "key": "ctrl+tab", "command": "workbench.action.quickOpenNavigateNextInEditorPicker", + "when": "inEditorsPicker && inQuickOpen" }, +{ "key": "ctrl+e", "command": "workbench.action.quickOpenNavigateNextInFilePicker", + "when": "inFilesPicker && inQuickOpen" }, +{ "key": "ctrl+p", "command": "workbench.action.quickOpenNavigateNextInFilePicker", + "when": "inFilesPicker && inQuickOpen" }, +{ "key": "ctrl+r", "command": "workbench.action.quickOpenNavigateNextInRecentFilesPicker", + "when": "inQuickOpen && inRecentFilesPicker" }, +{ "key": "ctrl+shift+tab", "command": "workbench.action.quickOpenNavigatePreviousInEditorPicker", + "when": "inEditorsPicker && inQuickOpen" }, +{ "key": "ctrl+shift+e", "command": "workbench.action.quickOpenNavigatePreviousInFilePicker", + "when": "inFilesPicker && inQuickOpen" }, +{ "key": "ctrl+shift+p", "command": "workbench.action.quickOpenNavigatePreviousInFilePicker", + "when": "inFilesPicker && inQuickOpen" }, +{ "key": "ctrl+shift+r", "command": "workbench.action.quickOpenNavigatePreviousInRecentFilesPicker", + "when": "inQuickOpen && inRecentFilesPicker" }, +{ "key": "ctrl+r", "command": "workbench.action.reloadWindow", + "when": "isDevelopment" }, +{ "key": "ctrl+shift+i", "command": "workbench.action.toggleDevTools", + "when": "isDevelopment" }, +{ "key": "ctrl+f4", "command": "extension.node-debug.pickLoadedScript", + "when": "debugType == 'node'" }, +{ "key": "ctrl+f4", "command": "extension.node-debug.pickLoadedScript", + "when": "debugType == 'node2'" }, +{ "key": "ctrl+shift+v", "command": "markdown.showPreview", + "when": "editorLangId == 'markdown'" }, +{ "key": "shift+alt+f12", "command": "references-view.find", + "when": "editorHasReferenceProvider" }, +{ "key": "f10", "command": "extension.node-debug.startWithStopOnEntry", + "when": "!inDebugMode && debugConfigurationType == 'node'" }, +{ "key": "ctrl+k v", "command": "markdown.showPreviewToSide", + "when": "editorLangId == 'markdown'" }, +{ "key": "f4", "command": "references-view.next", + "when": "reference-list.hasResult" }, +{ "key": "shift+f4", "command": "references-view.prev", + "when": "reference-list.hasResult" } +] \ No newline at end of file diff --git a/build/keybindings/doc.keybindings.osx.json b/build/keybindings/doc.keybindings.osx.json new file mode 100644 index 0000000000000000000000000000000000000000..e0903012d4b622da5d995e03d26944b99afab25f --- /dev/null +++ b/build/keybindings/doc.keybindings.osx.json @@ -0,0 +1,1018 @@ +[ +{ "key": "escape escape", "command": "workbench.action.exitZenMode", + "when": "inZenMode" }, +{ "key": "shift+escape", "command": "closeReferenceSearchEditor", + "when": "inReferenceSearchEditor && !config.editor.stablePeek" }, +{ "key": "escape", "command": "closeReferenceSearchEditor", + "when": "inReferenceSearchEditor && !config.editor.stablePeek" }, +{ "key": "shift+escape", "command": "cancelSelection", + "when": "editorHasSelection && textInputFocus" }, +{ "key": "escape", "command": "cancelSelection", + "when": "editorHasSelection && textInputFocus" }, +{ "key": "cmd+down", "command": "cursorBottom", + "when": "textInputFocus" }, +{ "key": "shift+cmd+down", "command": "cursorBottomSelect", + "when": "textInputFocus" }, +{ "key": "shift+alt+cmd+down", "command": "cursorColumnSelectDown", + "when": "textInputFocus" }, +{ "key": "shift+alt+cmd+left", "command": "cursorColumnSelectLeft", + "when": "textInputFocus" }, +{ "key": "shift+alt+cmd+pagedown", "command": "cursorColumnSelectPageDown", + "when": "textInputFocus" }, +{ "key": "shift+alt+cmd+pageup", "command": "cursorColumnSelectPageUp", + "when": "textInputFocus" }, +{ "key": "shift+alt+cmd+right", "command": "cursorColumnSelectRight", + "when": "textInputFocus" }, +{ "key": "shift+alt+cmd+up", "command": "cursorColumnSelectUp", + "when": "textInputFocus" }, +{ "key": "ctrl+n", "command": "cursorDown", + "when": "textInputFocus" }, +{ "key": "down", "command": "cursorDown", + "when": "textInputFocus" }, +{ "key": "shift+down", "command": "cursorDownSelect", + "when": "textInputFocus" }, +{ "key": "cmd+right", "command": "cursorEnd", + "when": "textInputFocus" }, +{ "key": "end", "command": "cursorEnd", + "when": "textInputFocus" }, +{ "key": "shift+cmd+right", "command": "cursorEndSelect", + "when": "textInputFocus" }, +{ "key": "shift+end", "command": "cursorEndSelect", + "when": "textInputFocus" }, +{ "key": "cmd+left", "command": "cursorHome", + "when": "textInputFocus" }, +{ "key": "home", "command": "cursorHome", + "when": "textInputFocus" }, +{ "key": "shift+cmd+left", "command": "cursorHomeSelect", + "when": "textInputFocus" }, +{ "key": "shift+home", "command": "cursorHomeSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+b", "command": "cursorLeft", + "when": "textInputFocus" }, +{ "key": "left", "command": "cursorLeft", + "when": "textInputFocus" }, +{ "key": "shift+left", "command": "cursorLeftSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+e", "command": "cursorLineEnd", + "when": "textInputFocus" }, +{ "key": "ctrl+a", "command": "cursorLineStart", + "when": "textInputFocus" }, +{ "key": "pagedown", "command": "cursorPageDown", + "when": "textInputFocus" }, +{ "key": "shift+pagedown", "command": "cursorPageDownSelect", + "when": "textInputFocus" }, +{ "key": "pageup", "command": "cursorPageUp", + "when": "textInputFocus" }, +{ "key": "shift+pageup", "command": "cursorPageUpSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+f", "command": "cursorRight", + "when": "textInputFocus" }, +{ "key": "right", "command": "cursorRight", + "when": "textInputFocus" }, +{ "key": "shift+right", "command": "cursorRightSelect", + "when": "textInputFocus" }, +{ "key": "cmd+up", "command": "cursorTop", + "when": "textInputFocus" }, +{ "key": "shift+cmd+up", "command": "cursorTopSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+p", "command": "cursorUp", + "when": "textInputFocus" }, +{ "key": "up", "command": "cursorUp", + "when": "textInputFocus" }, +{ "key": "shift+up", "command": "cursorUpSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+backspace", "command": "deleteLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+h", "command": "deleteLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "shift+backspace", "command": "deleteLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "backspace", "command": "deleteLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+delete", "command": "deleteRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+d", "command": "deleteRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "delete", "command": "deleteRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "cmd+a", "command": "editor.action.selectAll", + "when": "textInputFocus" }, +{ "key": "cmd+l", "command": "expandLineSelection", + "when": "textInputFocus" }, +{ "key": "ctrl+o", "command": "lineBreakInsert", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "shift+tab", "command": "outdent", + "when": "editorTextFocus && !editorReadonly && !editorTabMovesFocus" }, +{ "key": "shift+cmd+z", "command": "redo", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+pagedown", "command": "scrollLineDown", + "when": "textInputFocus" }, +{ "key": "ctrl+pageup", "command": "scrollLineUp", + "when": "textInputFocus" }, +{ "key": "cmd+pagedown", "command": "scrollPageDown", + "when": "textInputFocus" }, +{ "key": "cmd+pageup", "command": "scrollPageUp", + "when": "textInputFocus" }, +{ "key": "tab", "command": "tab", + "when": "editorTextFocus && !editorReadonly && !editorTabMovesFocus" }, +{ "key": "cmd+z", "command": "undo", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "shift+escape", "command": "removeSecondaryCursors", + "when": "editorHasMultipleSelections && textInputFocus" }, +{ "key": "escape", "command": "removeSecondaryCursors", + "when": "editorHasMultipleSelections && textInputFocus" }, +{ "key": "cmd+f", "command": "actions.find" }, +{ "key": "cmd+e", "command": "actions.findWithSelection" }, +{ "key": "enter", "command": "breakpointWidget.action.acceptInput", + "when": "breakpointWidgetVisible && inBreakpointWidget" }, +{ "key": "shift+escape", "command": "closeBreakpointWidget", + "when": "breakpointWidgetVisible && textInputFocus" }, +{ "key": "escape", "command": "closeBreakpointWidget", + "when": "breakpointWidgetVisible && textInputFocus" }, +{ "key": "shift+escape", "command": "closeReviewPanel", + "when": "reviewPanelVisible" }, +{ "key": "escape", "command": "closeReviewPanel", + "when": "reviewPanelVisible" }, +{ "key": "cmd+u", "command": "cursorUndo", + "when": "textInputFocus" }, +{ "key": "alt+right", "command": "cursorWordEndRight", + "when": "textInputFocus" }, +{ "key": "shift+alt+right", "command": "cursorWordEndRightSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+alt+left", "command": "cursorWordPartLeft", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+alt+left", "command": "cursorWordPartLeftSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+alt+right", "command": "cursorWordPartRight", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+alt+right", "command": "cursorWordPartRightSelect", + "when": "textInputFocus" }, +{ "key": "alt+left", "command": "cursorWordStartLeft", + "when": "textInputFocus" }, +{ "key": "shift+alt+left", "command": "cursorWordStartLeftSelect", + "when": "textInputFocus" }, +{ "key": "cmd+backspace", "command": "deleteAllLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "cmd+delete", "command": "deleteAllRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+k", "command": "deleteAllRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "alt+backspace", "command": "deleteWordLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+alt+backspace", "command": "deleteWordPartLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+alt+delete", "command": "deleteWordPartRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "alt+delete", "command": "deleteWordRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "cmd+k cmd+c", "command": "editor.action.addCommentLine", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "cmd+d", "command": "editor.action.addSelectionToNextFindMatch", + "when": "editorFocus" }, +{ "key": "alt+cmd+.", "command": "editor.action.autoFix", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+alt+a", "command": "editor.action.blockComment", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "cmd+f2", "command": "editor.action.changeAll", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "cmd+c", "command": "editor.action.clipboardCopyAction", + "when": "textInputFocus" }, +{ "key": "cmd+x", "command": "editor.action.clipboardCutAction", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "cmd+v", "command": "editor.action.clipboardPasteAction", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "cmd+/", "command": "editor.action.commentLine", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+alt+down", "command": "editor.action.copyLinesDownAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+alt+up", "command": "editor.action.copyLinesUpAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "cmd+k cmd+k", "command": "editor.action.defineKeybinding", + "when": "editorTextFocus && !editorReadonly && editorLangId == 'jsonc'" }, +{ "key": "shift+cmd+k", "command": "editor.action.deleteLines", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "f7", "command": "editor.action.diffReview.next", + "when": "isInDiffEditor" }, +{ "key": "shift+f7", "command": "editor.action.diffReview.prev", + "when": "isInDiffEditor" }, +{ "key": "alt+f3", "command": "editor.action.dirtydiff.next", + "when": "editorTextFocus" }, +{ "key": "shift+alt+f3", "command": "editor.action.dirtydiff.previous", + "when": "editorTextFocus" }, +{ "key": "cmd+f", "command": "editor.action.extensioneditor.showfind", + "when": "activeEditor == 'workbench.editor.extension'" }, +{ "key": "shift+alt+f", "command": "editor.action.formatDocument", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "cmd+k cmd+f", "command": "editor.action.formatSelection", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "cmd+f12", "command": "editor.action.goToImplementation", + "when": "editorHasImplementationProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "shift+cmd+.", "command": "editor.action.inPlaceReplace.down", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+cmd+,", "command": "editor.action.inPlaceReplace.up", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "cmd+]", "command": "editor.action.indentLines", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "alt+cmd+up", "command": "editor.action.insertCursorAbove", + "when": "editorTextFocus" }, +{ "key": "shift+alt+i", "command": "editor.action.insertCursorAtEndOfEachLineSelected", + "when": "editorTextFocus" }, +{ "key": "alt+cmd+down", "command": "editor.action.insertCursorBelow", + "when": "editorTextFocus" }, +{ "key": "cmd+enter", "command": "editor.action.insertLineAfter", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+cmd+enter", "command": "editor.action.insertLineBefore", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+j", "command": "editor.action.joinLines", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+cmd+\\", "command": "editor.action.jumpToBracket", + "when": "editorTextFocus" }, +{ "key": "alt+f8", "command": "editor.action.marker.next", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "f8", "command": "editor.action.marker.nextInFiles", + "when": "editorFocus && !editorReadonly" }, +{ "key": "shift+alt+f8", "command": "editor.action.marker.prev", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+f8", "command": "editor.action.marker.prevInFiles", + "when": "editorFocus && !editorReadonly" }, +{ "key": "alt+down", "command": "editor.action.moveLinesDownAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "alt+up", "command": "editor.action.moveLinesUpAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "cmd+k cmd+d", "command": "editor.action.moveSelectionToNextFindMatch", + "when": "editorFocus" }, +{ "key": "f3", "command": "editor.action.nextMatchFindAction", + "when": "editorFocus" }, +{ "key": "cmd+g", "command": "editor.action.nextMatchFindAction", + "when": "editorFocus" }, +{ "key": "cmd+f3", "command": "editor.action.nextSelectionMatchFindAction", + "when": "editorFocus" }, +{ "key": "shift+alt+o", "command": "editor.action.organizeImports", + "when": "editorTextFocus && !editorReadonly && supportedCodeAction =~ /(\\s|^)source\\.organizeImports\\b/" }, +{ "key": "cmd+[", "command": "editor.action.outdentLines", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "alt+f12", "command": "editor.action.peekDefinition", + "when": "editorHasDefinitionProvider && editorTextFocus && !inReferenceSearchEditor && !isInEmbeddedEditor" }, +{ "key": "shift+cmd+f12", "command": "editor.action.peekImplementation", + "when": "editorHasImplementationProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "shift+f3", "command": "editor.action.previousMatchFindAction", + "when": "editorFocus" }, +{ "key": "shift+cmd+g", "command": "editor.action.previousMatchFindAction", + "when": "editorFocus" }, +{ "key": "shift+cmd+f3", "command": "editor.action.previousSelectionMatchFindAction", + "when": "editorFocus" }, +{ "key": "cmd+.", "command": "editor.action.quickFix", + "when": "editorHasCodeActionsProvider && editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+r", "command": "editor.action.refactor", + "when": "editorHasCodeActionsProvider && editorTextFocus && !editorReadonly" }, +{ "key": "shift+f12", "command": "editor.action.referenceSearch.trigger", + "when": "editorHasReferenceProvider && editorTextFocus && !inReferenceSearchEditor && !isInEmbeddedEditor" }, +{ "key": "cmd+k cmd+u", "command": "editor.action.removeCommentLine", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "f2", "command": "editor.action.rename", + "when": "editorHasRenameProvider && editorTextFocus && !editorReadonly" }, +{ "key": "f12", "command": "editor.action.revealDefinition", + "when": "editorHasDefinitionProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "cmd+k f12", "command": "editor.action.revealDefinitionAside", + "when": "editorHasDefinitionProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "shift+cmd+l", "command": "editor.action.selectHighlights", + "when": "editorFocus" }, +{ "key": "alt+f1", "command": "editor.action.showAccessibilityHelp", + "when": "editorFocus" }, +{ "key": "shift+f10", "command": "editor.action.showContextMenu", + "when": "textInputFocus" }, +{ "key": "cmd+k cmd+i", "command": "editor.action.showHover", + "when": "editorTextFocus" }, +{ "key": "ctrl+shift+cmd+right", "command": "editor.action.smartSelect.expand", + "when": "editorTextFocus" }, +{ "key": "ctrl+shift+cmd+left", "command": "editor.action.smartSelect.shrink", + "when": "editorTextFocus" }, +{ "key": "alt+cmd+f", "command": "editor.action.startFindReplaceAction" }, +{ "key": "ctrl+shift+m", "command": "editor.action.toggleTabFocusMode" }, +{ "key": "alt+z", "command": "editor.action.toggleWordWrap" }, +{ "key": "ctrl+t", "command": "editor.action.transposeLetters", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "shift+cmd+space", "command": "editor.action.triggerParameterHints", + "when": "editorHasSignatureHelpProvider && editorTextFocus" }, +{ "key": "ctrl+space", "command": "editor.action.triggerSuggest", + "when": "editorHasCompletionItemProvider && textInputFocus && !editorReadonly" }, +{ "key": "cmd+k cmd+x", "command": "editor.action.trimTrailingWhitespace", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "cmd+c", "command": "editor.action.webvieweditor.copy", + "when": "!editorFocus && !inputFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "cmd+c", "command": "editor.action.webvieweditor.copy", + "when": "!editorFocus && !inputFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "cmd+x", "command": "editor.action.webvieweditor.cut", + "when": "!editorFocus && !inputFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "cmd+x", "command": "editor.action.webvieweditor.cut", + "when": "!editorFocus && !inputFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "escape", "command": "editor.action.webvieweditor.hideFind", + "when": "webviewFindWidgetVisible && !editorFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "escape", "command": "editor.action.webvieweditor.hideFind", + "when": "webviewFindWidgetVisible && !editorFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "cmd+v", "command": "editor.action.webvieweditor.paste", + "when": "!editorFocus && !inputFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "cmd+v", "command": "editor.action.webvieweditor.paste", + "when": "!editorFocus && !inputFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "shift+cmd+z", "command": "editor.action.webvieweditor.redo", + "when": "!editorFocus && !inputFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "shift+cmd+z", "command": "editor.action.webvieweditor.redo", + "when": "!editorFocus && !inputFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "cmd+a", "command": "editor.action.webvieweditor.selectAll", + "when": "!editorFocus && !inputFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "cmd+a", "command": "editor.action.webvieweditor.selectAll", + "when": "!editorFocus && !inputFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "cmd+f", "command": "editor.action.webvieweditor.showFind", + "when": "!editorFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "cmd+f", "command": "editor.action.webvieweditor.showFind", + "when": "!editorFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "cmd+z", "command": "editor.action.webvieweditor.undo", + "when": "!editorFocus && !inputFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "cmd+z", "command": "editor.action.webvieweditor.undo", + "when": "!editorFocus && !inputFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "f7", "command": "editor.action.wordHighlight.next", + "when": "editorTextFocus && hasWordHighlights" }, +{ "key": "shift+f7", "command": "editor.action.wordHighlight.prev", + "when": "editorTextFocus && hasWordHighlights" }, +{ "key": "cmd+k cmd+i", "command": "editor.debug.action.showDebugHover", + "when": "editorTextFocus && inDebugMode" }, +{ "key": "f9", "command": "editor.debug.action.toggleBreakpoint", + "when": "editorTextFocus" }, +{ "key": "tab", "command": "editor.emmet.action.expandAbbreviation", + "when": "config.emmet.triggerExpansionOnTab && editorTextFocus && !editorReadonly && !editorTabMovesFocus" }, +{ "key": "alt+cmd+[", "command": "editor.fold", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+0", "command": "editor.foldAll", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+/", "command": "editor.foldAllBlockComments", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+8", "command": "editor.foldAllMarkerRegions", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+1", "command": "editor.foldLevel1", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+2", "command": "editor.foldLevel2", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+3", "command": "editor.foldLevel3", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+4", "command": "editor.foldLevel4", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+5", "command": "editor.foldLevel5", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+6", "command": "editor.foldLevel6", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+7", "command": "editor.foldLevel7", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+[", "command": "editor.foldRecursively", + "when": "editorTextFocus" }, +{ "key": "alt+cmd+]", "command": "editor.unfold", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+j", "command": "editor.unfoldAll", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+9", "command": "editor.unfoldAllMarkerRegions", + "when": "editorTextFocus" }, +{ "key": "cmd+k cmd+]", "command": "editor.unfoldRecursively", + "when": "editorTextFocus" }, +{ "key": "tab", "command": "insertSnippet", + "when": "editorTextFocus && hasSnippetCompletions && !editorTabMovesFocus && !inSnippetMode" }, +{ "key": "ctrl+enter", "command": "openReferenceToSide", + "when": "referenceSearchTreeFocused && referenceSearchVisible" }, +{ "key": "enter", "command": "repl.action.acceptInput", + "when": "inDebugRepl && textInputFocus" }, +{ "key": "escape", "command": "settings.action.clearSearchResults", + "when": "inSettingsSearch" }, +{ "key": "cmd+.", "command": "settings.action.editFocusedSetting", + "when": "inSettingsSearch" }, +{ "key": "enter", "command": "settings.action.focusNextSetting", + "when": "inSettingsSearch" }, +{ "key": "shift+enter", "command": "settings.action.focusPreviousSetting", + "when": "inSettingsSearch" }, +{ "key": "down", "command": "settings.action.focusSettingsFile", + "when": "inSettingsSearch && !suggestWidgetVisible" }, +{ "key": "cmd+f", "command": "settings.action.search", + "when": "inSettingsEditor" }, +{ "key": "alt+f5", "command": "workbench.action.editor.nextChange", + "when": "editorTextFocus" }, +{ "key": "shift+alt+f5", "command": "workbench.action.editor.previousChange", + "when": "editorTextFocus" }, +{ "key": "shift+escape", "command": "closeFindWidget", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "escape", "command": "closeFindWidget", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "alt+cmd+enter", "command": "editor.action.replaceAll", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "shift+cmd+1", "command": "editor.action.replaceOne", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "alt+enter", "command": "editor.action.selectAllMatches", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "alt+cmd+c", "command": "toggleFindCaseSensitive", + "when": "editorFocus" }, +{ "key": "alt+cmd+l", "command": "toggleFindInSelection", + "when": "editorFocus" }, +{ "key": "alt+cmd+r", "command": "toggleFindRegex", + "when": "editorFocus" }, +{ "key": "alt+cmd+w", "command": "toggleFindWholeWord", + "when": "editorFocus" }, +{ "key": "tab", "command": "jumpToNextSnippetPlaceholder", + "when": "editorTextFocus && hasNextTabstop && inSnippetMode" }, +{ "key": "shift+tab", "command": "jumpToPrevSnippetPlaceholder", + "when": "editorTextFocus && hasPrevTabstop && inSnippetMode" }, +{ "key": "escape", "command": "leaveEditorMessage", + "when": "messageVisible" }, +{ "key": "shift+escape", "command": "leaveSnippet", + "when": "editorTextFocus && inSnippetMode" }, +{ "key": "escape", "command": "leaveSnippet", + "when": "editorTextFocus && inSnippetMode" }, +{ "key": "shift+escape", "command": "closeDirtyDiff", + "when": "dirtyDiffVisible" }, +{ "key": "escape", "command": "closeDirtyDiff", + "when": "dirtyDiffVisible" }, +{ "key": "shift+escape", "command": "closeMarkersNavigation", + "when": "editorFocus && markersNavigationVisible" }, +{ "key": "escape", "command": "closeMarkersNavigation", + "when": "editorFocus && markersNavigationVisible" }, +{ "key": "f4", "command": "goToNextReferenceFromEmbeddedEditor", + "when": "inReferenceSearchEditor" }, +{ "key": "shift+f4", "command": "goToPreviousReferenceFromEmbeddedEditor", + "when": "inReferenceSearchEditor" }, +{ "key": "shift+escape", "command": "closeParameterHints", + "when": "editorFocus && parameterHintsVisible" }, +{ "key": "escape", "command": "closeParameterHints", + "when": "editorFocus && parameterHintsVisible" }, +{ "key": "ctrl+n", "command": "showNextParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "alt+down", "command": "showNextParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "down", "command": "showNextParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "ctrl+p", "command": "showPrevParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "alt+up", "command": "showPrevParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "up", "command": "showPrevParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "tab", "command": "acceptSelectedSuggestion", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "enter", "command": "acceptSelectedSuggestionOnEnter", + "when": "acceptSuggestionOnEnter && suggestWidgetVisible && suggestionMakesTextEdit && textInputFocus" }, +{ "key": "shift+escape", "command": "hideSuggestWidget", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "escape", "command": "hideSuggestWidget", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "tab", "command": "insertBestCompletion", + "when": "atEndOfWord && !hasOtherSuggestions && !inSnippetMode && !suggestWidgetVisible && config.editor.tabCompletion == 'on'" }, +{ "key": "tab", "command": "insertNextSuggestion", + "when": "hasOtherSuggestions && textInputFocus && !inSnippetMode && !suggestWidgetVisible && config.editor.tabCompletion == 'on'" }, +{ "key": "shift+tab", "command": "insertPrevSuggestion", + "when": "hasOtherSuggestions && textInputFocus && !inSnippetMode && !suggestWidgetVisible && config.editor.tabCompletion == 'on'" }, +{ "key": "cmd+pagedown", "command": "selectNextPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "pagedown", "command": "selectNextPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+n", "command": "selectNextSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "cmd+down", "command": "selectNextSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "down", "command": "selectNextSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "cmd+pageup", "command": "selectPrevPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "pageup", "command": "selectPrevPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+p", "command": "selectPrevSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "cmd+up", "command": "selectPrevSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "up", "command": "selectPrevSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+space", "command": "toggleSuggestionDetails", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+alt+space", "command": "toggleSuggestionFocus", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "enter", "command": "acceptRenameInput", + "when": "editorFocus && renameInputVisible" }, +{ "key": "shift+escape", "command": "cancelRenameInput", + "when": "editorFocus && renameInputVisible" }, +{ "key": "escape", "command": "cancelRenameInput", + "when": "editorFocus && renameInputVisible" }, +{ "key": "shift+cmd+;", "command": "breadcrumbs.focus", + "when": "breadcrumbsPossible" }, +{ "key": "shift+cmd+.", "command": "breadcrumbs.focusAndSelect", + "when": "breadcrumbsPossible" }, +{ "key": "alt+right", "command": "breadcrumbs.focusNext", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "right", "command": "breadcrumbs.focusNext", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "alt+left", "command": "breadcrumbs.focusPrevious", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "left", "command": "breadcrumbs.focusPrevious", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "cmd+enter", "command": "breadcrumbs.revealFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "space", "command": "breadcrumbs.revealFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "cmd+enter", "command": "breadcrumbs.revealFocusedFromTreeAside", + "when": "breadcrumbsActive && breadcrumbsVisible && listFocus && !inputFocus" }, +{ "key": "down", "command": "breadcrumbs.selectFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "enter", "command": "breadcrumbs.selectFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "shift+cmd+.", "command": "breadcrumbs.toggleToOn", + "when": "!config.breadcrumbs.enabled" }, +{ "key": "shift+escape", "command": "closeAccessibilityHelp", + "when": "accessibilityHelpWidgetVisible && editorFocus" }, +{ "key": "escape", "command": "closeAccessibilityHelp", + "when": "accessibilityHelpWidgetVisible && editorFocus" }, +{ "key": "escape", "command": "closeReplaceInFilesWidget", + "when": "replaceInputBoxFocus && searchViewletVisible" }, +{ "key": "alt+cmd+c", "command": "copyFilePath", + "when": "!editorFocus" }, +{ "key": "shift+alt+cmd+c", "command": "copyRelativeFilePath", + "when": "!editorFocus" }, +{ "key": "alt+enter", "command": "debug.openBreakpointToSide", + "when": "breakpointsFocused" }, +{ "key": "cmd+enter", "command": "debug.openBreakpointToSide", + "when": "breakpointsFocused" }, +{ "key": "cmd+backspace", "command": "debug.removeBreakpoint", + "when": "breakpointsFocused && !breakpointSelected" }, +{ "key": "cmd+backspace", "command": "debug.removeWatchExpression", + "when": "watchExpressionsFocused && !expressionSelected" }, +{ "key": "shift+f9", "command": "editor.debug.action.toggleInlineBreakpoint", + "when": "editorTextFocus" }, +{ "key": "ctrl+enter", "command": "explorer.openToSide", + "when": "explorerViewletFocus && explorerViewletVisible && !inputFocus" }, +{ "key": "shift+alt+f", "command": "filesExplorer.findInFolder", + "when": "explorerResourceIsFolder && explorerViewletVisible && filesExplorerFocus && !inputFocus && resourceScheme == 'file'" }, +{ "key": "alt+down", "command": "history.showNext", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "down", "command": "history.showNext", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "alt+up", "command": "history.showPrevious", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "up", "command": "history.showPrevious", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "escape", "command": "keybindings.editor.clearSearchResults", + "when": "inKeybindings && inKeybindingsSearch" }, +{ "key": "cmd+c", "command": "keybindings.editor.copyKeybindingEntry", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "cmd+k cmd+k", "command": "keybindings.editor.defineKeybinding", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "cmd+k cmd+e", "command": "keybindings.editor.defineWhenExpression", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "down", "command": "keybindings.editor.focusKeybindings", + "when": "inKeybindings && inKeybindingsSearch" }, +{ "key": "alt+cmd+k", "command": "keybindings.editor.recordSearchKeys", + "when": "inKeybindings && inKeybindingsSearch" }, +{ "key": "cmd+k cmd+backspace", "command": "keybindings.editor.removeKeybinding", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "cmd+f", "command": "keybindings.editor.searchKeybindings", + "when": "inKeybindings" }, +{ "key": "alt+cmd+p", "command": "keybindings.editor.toggleSortByPrecedence", + "when": "inKeybindings" }, +{ "key": "escape", "command": "list.clear", + "when": "listFocus && listHasSelectionOrFocus && !inputFocus" }, +{ "key": "cmd+up", "command": "list.collapse", + "when": "listFocus && !inputFocus" }, +{ "key": "left", "command": "list.collapse", + "when": "listFocus && !inputFocus" }, +{ "key": "right", "command": "list.expand", + "when": "listFocus && !inputFocus" }, +{ "key": "shift+down", "command": "list.expandSelectionDown", + "when": "listFocus && listSupportsMultiselect && !inputFocus" }, +{ "key": "shift+up", "command": "list.expandSelectionUp", + "when": "listFocus && listSupportsMultiselect && !inputFocus" }, +{ "key": "ctrl+n", "command": "list.focusDown", + "when": "listFocus && !inputFocus" }, +{ "key": "down", "command": "list.focusDown", + "when": "listFocus && !inputFocus" }, +{ "key": "home", "command": "list.focusFirst", + "when": "listFocus && !inputFocus" }, +{ "key": "end", "command": "list.focusLast", + "when": "listFocus && !inputFocus" }, +{ "key": "pagedown", "command": "list.focusPageDown", + "when": "listFocus && !inputFocus" }, +{ "key": "pageup", "command": "list.focusPageUp", + "when": "listFocus && !inputFocus" }, +{ "key": "ctrl+p", "command": "list.focusUp", + "when": "listFocus && !inputFocus" }, +{ "key": "up", "command": "list.focusUp", + "when": "listFocus && !inputFocus" }, +{ "key": "cmd+down", "command": "list.select", + "when": "listFocus && !inputFocus" }, +{ "key": "enter", "command": "list.select", + "when": "listFocus && !inputFocus" }, +{ "key": "cmd+a", "command": "list.selectAll", + "when": "listFocus && listSupportsMultiselect && !inputFocus" }, +{ "key": "space", "command": "list.toggleExpand", + "when": "listFocus && !inputFocus" }, +{ "key": "cmd+backspace", "command": "notification.clear", + "when": "notificationFocus" }, +{ "key": "left", "command": "notification.collapse", + "when": "notificationFocus" }, +{ "key": "right", "command": "notification.expand", + "when": "notificationFocus" }, +{ "key": "enter", "command": "notification.toggle", + "when": "notificationFocus" }, +{ "key": "space", "command": "notification.toggle", + "when": "notificationFocus" }, +{ "key": "home", "command": "notifications.focusFirstToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "pageup", "command": "notifications.focusFirstToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "end", "command": "notifications.focusLastToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "pagedown", "command": "notifications.focusLastToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "down", "command": "notifications.focusNextToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "up", "command": "notifications.focusPreviousToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "ctrl+enter", "command": "problems.action.openToSide", + "when": "problemFocus" }, +{ "key": "cmd+.", "command": "problems.action.showQuickFixes", + "when": "problemFocus" }, +{ "key": "alt+cmd+r", "command": "revealFileInOS", + "when": "!editorFocus" }, +{ "key": "cmd+enter", "command": "scm.acceptInput", + "when": "scmRepository" }, +{ "key": "escape", "command": "search.action.cancel", + "when": "listFocus && searchViewletVisible && !inputFocus" }, +{ "key": "cmd+c", "command": "search.action.copyMatch", + "when": "fileMatchOrMatchFocus" }, +{ "key": "alt+cmd+c", "command": "search.action.copyPath", + "when": "fileMatchOrFolderMatchFocus" }, +{ "key": "f4", "command": "search.action.focusNextSearchResult", + "when": "hasSearchResult" }, +{ "key": "shift+f4", "command": "search.action.focusPreviousSearchResult", + "when": "hasSearchResult" }, +{ "key": "cmd+up", "command": "search.action.focusSearchFromResults", + "when": "firstMatchFocus && searchViewletVisible" }, +{ "key": "ctrl+enter", "command": "search.action.openResultToSide", + "when": "fileMatchOrMatchFocus && searchViewletVisible" }, +{ "key": "cmd+backspace", "command": "search.action.remove", + "when": "fileMatchOrMatchFocus && searchViewletVisible" }, +{ "key": "shift+cmd+1", "command": "search.action.replace", + "when": "matchFocus && replaceActive && searchViewletVisible" }, +{ "key": "alt+cmd+enter", "command": "search.action.replaceAll", + "when": "replaceActive && searchViewletVisible && !findWidgetVisible" }, +{ "key": "shift+cmd+enter", "command": "search.action.replaceAllInFile", + "when": "fileMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "shift+cmd+1", "command": "search.action.replaceAllInFile", + "when": "fileMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "shift+cmd+enter", "command": "search.action.replaceAllInFolder", + "when": "folderMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "shift+cmd+1", "command": "search.action.replaceAllInFolder", + "when": "folderMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "cmd+down", "command": "search.focus.nextInputBox", + "when": "inputBoxFocus && searchViewletVisible" }, +{ "key": "cmd+up", "command": "search.focus.previousInputBox", + "when": "inputBoxFocus && searchViewletVisible && !searchInputBoxFocus" }, +{ "key": "down", "command": "settings.action.focusSettingsFromSearch", + "when": "inSettingsSearch && !suggestWidgetVisible" }, +{ "key": "enter", "command": "settings.action.focusSettingsList", + "when": "inSettingsEditor && settingsTocRowFocus" }, +{ "key": "shift+f9", "command": "settings.action.showContextMenu", + "when": "inSettingsEditor" }, +{ "key": "alt+cmd+c", "command": "toggleSearchCaseSensitive", + "when": "searchViewletFocus && searchViewletVisible && !fileMatchOrFolderMatchFocus" }, +{ "key": "alt+cmd+r", "command": "toggleSearchRegex", + "when": "searchViewletFocus && searchViewletVisible" }, +{ "key": "alt+cmd+w", "command": "toggleSearchWholeWord", + "when": "searchViewletFocus && searchViewletVisible" }, +{ "key": "cmd+w", "command": "workbench.action.closeActiveEditor" }, +{ "key": "cmd+k cmd+w", "command": "workbench.action.closeAllEditors" }, +{ "key": "cmd+k shift+cmd+w", "command": "workbench.action.closeAllGroups" }, +{ "key": "cmd+k w", "command": "workbench.action.closeEditorsInGroup" }, +{ "key": "cmd+k f", "command": "workbench.action.closeFolder" }, +{ "key": "cmd+w", "command": "workbench.action.closeGroup", + "when": "activeEditorGroupEmpty && multipleEditorGroups" }, +{ "key": "alt+cmd+t", "command": "workbench.action.closeOtherEditors" }, +{ "key": "shift+escape", "command": "workbench.action.closeQuickOpen", + "when": "inQuickOpen" }, +{ "key": "escape", "command": "workbench.action.closeQuickOpen", + "when": "inQuickOpen" }, +{ "key": "cmd+k u", "command": "workbench.action.closeUnmodifiedEditors" }, +{ "key": "cmd+w", "command": "workbench.action.closeWindow", + "when": "!editorIsOpen && !multipleEditorGroups" }, +{ "key": "shift+cmd+w", "command": "workbench.action.closeWindow" }, +{ "key": "alt+f5", "command": "workbench.action.compareEditor.nextChange", + "when": "textCompareEditorVisible" }, +{ "key": "shift+alt+f5", "command": "workbench.action.compareEditor.previousChange", + "when": "textCompareEditorVisible" }, +{ "key": "f5", "command": "workbench.action.debug.continue", + "when": "inDebugMode" }, +{ "key": "f6", "command": "workbench.action.debug.pause", + "when": "inDebugMode" }, +{ "key": "shift+cmd+f5", "command": "workbench.action.debug.restart", + "when": "inDebugMode" }, +{ "key": "ctrl+f5", "command": "workbench.action.debug.run", + "when": "!inDebugMode" }, +{ "key": "f5", "command": "workbench.action.debug.start", + "when": "!inDebugMode" }, +{ "key": "shift+f11", "command": "workbench.action.debug.stepOut", + "when": "inDebugMode" }, +{ "key": "f10", "command": "workbench.action.debug.stepOver", + "when": "inDebugMode" }, +{ "key": "shift+f5", "command": "workbench.action.debug.stop", + "when": "inDebugMode" }, +{ "key": "cmd+k m", "command": "workbench.action.editor.changeLanguageMode" }, +{ "key": "cmd+k p", "command": "workbench.action.files.copyPathOfActiveFile" }, +{ "key": "cmd+n", "command": "workbench.action.files.newUntitledFile" }, +{ "key": "cmd+o", "command": "workbench.action.files.openFileFolder" }, +{ "key": "cmd+k r", "command": "workbench.action.files.revealActiveFileInWindows" }, +{ "key": "cmd+s", "command": "workbench.action.files.save" }, +{ "key": "alt+cmd+s", "command": "workbench.action.files.saveAll" }, +{ "key": "shift+cmd+s", "command": "workbench.action.files.saveAs" }, +{ "key": "cmd+k s", "command": "workbench.action.files.saveWithoutFormatting" }, +{ "key": "cmd+k o", "command": "workbench.action.files.showOpenedFileInNewWindow" }, +{ "key": "shift+cmd+f", "command": "workbench.action.findInFiles" }, +{ "key": "cmd+k cmd+up", "command": "workbench.action.focusAboveGroup" }, +{ "key": "cmd+k cmd+down", "command": "workbench.action.focusBelowGroup" }, +{ "key": "cmd+8", "command": "workbench.action.focusEighthEditorGroup" }, +{ "key": "cmd+5", "command": "workbench.action.focusFifthEditorGroup" }, +{ "key": "cmd+1", "command": "workbench.action.focusFirstEditorGroup" }, +{ "key": "cmd+4", "command": "workbench.action.focusFourthEditorGroup" }, +{ "key": "cmd+k cmd+left", "command": "workbench.action.focusLeftGroup" }, +{ "key": "cmd+k cmd+right", "command": "workbench.action.focusRightGroup" }, +{ "key": "cmd+2", "command": "workbench.action.focusSecondEditorGroup" }, +{ "key": "cmd+7", "command": "workbench.action.focusSeventhEditorGroup" }, +{ "key": "cmd+0", "command": "workbench.action.focusSideBar" }, +{ "key": "cmd+6", "command": "workbench.action.focusSixthEditorGroup" }, +{ "key": "cmd+3", "command": "workbench.action.focusThirdEditorGroup" }, +{ "key": "ctrl+g", "command": "workbench.action.gotoLine" }, +{ "key": "shift+cmd+o", "command": "workbench.action.gotoSymbol" }, +{ "key": "escape", "command": "workbench.action.hideInterfaceOverview", + "when": "interfaceOverviewVisible" }, +{ "key": "down", "command": "workbench.action.interactivePlayground.arrowDown", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "up", "command": "workbench.action.interactivePlayground.arrowUp", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "pagedown", "command": "workbench.action.interactivePlayground.pageDown", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "pageup", "command": "workbench.action.interactivePlayground.pageUp", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "cmd+k enter", "command": "workbench.action.keepEditor" }, +{ "key": "cmd+k cmd+r", "command": "workbench.action.keybindingsReference" }, +{ "key": "cmd+9", "command": "workbench.action.lastEditorInGroup" }, +{ "key": "ctrl+0", "command": "workbench.action.lastEditorInGroup" }, +{ "key": "cmd+k down", "command": "workbench.action.moveActiveEditorGroupDown" }, +{ "key": "cmd+k left", "command": "workbench.action.moveActiveEditorGroupLeft" }, +{ "key": "cmd+k right", "command": "workbench.action.moveActiveEditorGroupRight" }, +{ "key": "cmd+k up", "command": "workbench.action.moveActiveEditorGroupUp" }, +{ "key": "cmd+k shift+cmd+left", "command": "workbench.action.moveEditorLeftInGroup" }, +{ "key": "cmd+k shift+cmd+right", "command": "workbench.action.moveEditorRightInGroup" }, +{ "key": "ctrl+cmd+1", "command": "workbench.action.moveEditorToFirstGroup" }, +{ "key": "ctrl+cmd+9", "command": "workbench.action.moveEditorToLastGroup" }, +{ "key": "ctrl+cmd+right", "command": "workbench.action.moveEditorToNextGroup" }, +{ "key": "ctrl+cmd+left", "command": "workbench.action.moveEditorToPreviousGroup" }, +{ "key": "ctrl+-", "command": "workbench.action.navigateBack" }, +{ "key": "ctrl+shift+-", "command": "workbench.action.navigateForward" }, +{ "key": "cmd+k cmd+q", "command": "workbench.action.navigateToLastEditLocation" }, +{ "key": "shift+cmd+n", "command": "workbench.action.newWindow" }, +{ "key": "shift+cmd+]", "command": "workbench.action.nextEditor" }, +{ "key": "alt+cmd+right", "command": "workbench.action.nextEditor" }, +{ "key": "ctrl+1", "command": "workbench.action.openEditorAtIndex1" }, +{ "key": "ctrl+2", "command": "workbench.action.openEditorAtIndex2" }, +{ "key": "ctrl+3", "command": "workbench.action.openEditorAtIndex3" }, +{ "key": "ctrl+4", "command": "workbench.action.openEditorAtIndex4" }, +{ "key": "ctrl+5", "command": "workbench.action.openEditorAtIndex5" }, +{ "key": "ctrl+6", "command": "workbench.action.openEditorAtIndex6" }, +{ "key": "ctrl+7", "command": "workbench.action.openEditorAtIndex7" }, +{ "key": "ctrl+8", "command": "workbench.action.openEditorAtIndex8" }, +{ "key": "ctrl+9", "command": "workbench.action.openEditorAtIndex9" }, +{ "key": "cmd+k cmd+s", "command": "workbench.action.openGlobalKeybindings" }, +{ "key": "ctrl+tab", "command": "workbench.action.openNextRecentlyUsedEditorInGroup" }, +{ "key": "ctrl+shift+tab", "command": "workbench.action.openPreviousRecentlyUsedEditorInGroup" }, +{ "key": "ctrl+r", "command": "workbench.action.openRecent" }, +{ "key": "cmd+,", "command": "workbench.action.openSettings" }, +{ "key": "cmd+f", "command": "problems.action.focusFilter", + "when": "problemsViewFocus" }, +{ "key": "shift+cmd+u", "command": "workbench.action.output.toggleOutput" }, +{ "key": "cmd+c", "command": "problems.action.copy", + "when": "problemFocus" }, +{ "key": "cmd+down", "command": "problems.action.focusProblemsFromFilter", + "when": "problemsFilterFocus" }, +{ "key": "shift+cmd+[", "command": "workbench.action.previousEditor" }, +{ "key": "alt+cmd+left", "command": "workbench.action.previousEditor" }, +{ "key": "cmd+p", "command": "workbench.action.quickOpen" }, +{ "key": "ctrl+q", "command": "workbench.action.quickOpenView" }, +{ "key": "cmd+q", "command": "workbench.action.quit" }, +{ "key": "shift+cmd+t", "command": "workbench.action.reopenClosedEditor" }, +{ "key": "shift+cmd+h", "command": "workbench.action.replaceInFiles" }, +{ "key": "shift+cmd+j", "command": "workbench.action.search.toggleQueryDetails", + "when": "searchViewletVisible" }, +{ "key": "cmd+k cmd+t", "command": "workbench.action.selectTheme" }, +{ "key": "alt+cmd+tab", "command": "workbench.action.showAllEditors" }, +{ "key": "cmd+t", "command": "workbench.action.showAllSymbols" }, +{ "key": "f1", "command": "workbench.action.showCommands" }, +{ "key": "shift+cmd+p", "command": "workbench.action.showCommands" }, +{ "key": "cmd+\\", "command": "workbench.action.splitEditor" }, +{ "key": "cmd+k cmd+\\", "command": "workbench.action.splitEditorOrthogonal" }, +{ "key": "ctrl+w", "command": "workbench.action.switchWindow" }, +{ "key": "shift+cmd+b", "command": "workbench.action.tasks.build" }, +{ "key": "escape", "command": "workbench.action.terminal.clearSelection", + "when": "terminalFocus && terminalTextSelected && !terminalFindWidgetVisible" }, +{ "key": "cmd+c", "command": "workbench.action.terminal.copySelection", + "when": "terminalFocus && terminalTextSelected" }, +{ "key": "cmd+backspace", "command": "workbench.action.terminal.deleteToLineStart", + "when": "terminalFocus" }, +{ "key": "alt+backspace", "command": "workbench.action.terminal.deleteWordLeft", + "when": "terminalFocus" }, +{ "key": "alt+delete", "command": "workbench.action.terminal.deleteWordRight", + "when": "terminalFocus" }, +{ "key": "f3", "command": "workbench.action.terminal.findNext", + "when": "terminalFindWidgetFocused" }, +{ "key": "cmd+g", "command": "workbench.action.terminal.findNext", + "when": "terminalFindWidgetFocused" }, +{ "key": "f3", "command": "workbench.action.terminal.findNextTerminalFocus", + "when": "terminalFocus" }, +{ "key": "cmd+g", "command": "workbench.action.terminal.findNextTerminalFocus", + "when": "terminalFocus" }, +{ "key": "shift+f3", "command": "workbench.action.terminal.findPrevious", + "when": "terminalFindWidgetFocused" }, +{ "key": "shift+cmd+g", "command": "workbench.action.terminal.findPrevious", + "when": "terminalFindWidgetFocused" }, +{ "key": "shift+f3", "command": "workbench.action.terminal.findPreviousTerminalFocus", + "when": "terminalFocus" }, +{ "key": "shift+cmd+g", "command": "workbench.action.terminal.findPreviousTerminalFocus", + "when": "terminalFocus" }, +{ "key": "cmd+f", "command": "workbench.action.terminal.focusFindWidget", + "when": "terminalFindWidgetFocused" }, +{ "key": "cmd+f", "command": "workbench.action.terminal.focusFindWidget", + "when": "terminalFocus" }, +{ "key": "alt+cmd+down", "command": "workbench.action.terminal.focusNextPane", + "when": "terminalFocus" }, +{ "key": "alt+cmd+right", "command": "workbench.action.terminal.focusNextPane", + "when": "terminalFocus" }, +{ "key": "alt+cmd+up", "command": "workbench.action.terminal.focusPreviousPane", + "when": "terminalFocus" }, +{ "key": "alt+cmd+left", "command": "workbench.action.terminal.focusPreviousPane", + "when": "terminalFocus" }, +{ "key": "shift+escape", "command": "workbench.action.terminal.hideFindWidget", + "when": "terminalFindWidgetVisible && terminalFocus" }, +{ "key": "escape", "command": "workbench.action.terminal.hideFindWidget", + "when": "terminalFindWidgetVisible && terminalFocus" }, +{ "key": "cmd+right", "command": "workbench.action.terminal.moveToLineEnd", + "when": "terminalFocus" }, +{ "key": "cmd+left", "command": "workbench.action.terminal.moveToLineStart", + "when": "terminalFocus" }, +{ "key": "ctrl+shift+`", "command": "workbench.action.terminal.new" }, +{ "key": "shift+cmd+c", "command": "workbench.action.terminal.openNativeConsole", + "when": "!terminalFocus" }, +{ "key": "ctrl+cmd+down", "command": "workbench.action.terminal.resizePaneDown", + "when": "terminalFocus" }, +{ "key": "ctrl+cmd+left", "command": "workbench.action.terminal.resizePaneLeft", + "when": "terminalFocus" }, +{ "key": "ctrl+cmd+right", "command": "workbench.action.terminal.resizePaneRight", + "when": "terminalFocus" }, +{ "key": "ctrl+cmd+up", "command": "workbench.action.terminal.resizePaneUp", + "when": "terminalFocus" }, +{ "key": "alt+cmd+pagedown", "command": "workbench.action.terminal.scrollDown", + "when": "terminalFocus" }, +{ "key": "pagedown", "command": "workbench.action.terminal.scrollDownPage", + "when": "terminalFocus" }, +{ "key": "cmd+end", "command": "workbench.action.terminal.scrollToBottom", + "when": "terminalFocus" }, +{ "key": "cmd+down", "command": "workbench.action.terminal.scrollToNextCommand", + "when": "terminalFocus" }, +{ "key": "cmd+up", "command": "workbench.action.terminal.scrollToPreviousCommand", + "when": "terminalFocus" }, +{ "key": "cmd+home", "command": "workbench.action.terminal.scrollToTop", + "when": "terminalFocus" }, +{ "key": "alt+cmd+pageup", "command": "workbench.action.terminal.scrollUp", + "when": "terminalFocus" }, +{ "key": "pageup", "command": "workbench.action.terminal.scrollUpPage", + "when": "terminalFocus" }, +{ "key": "cmd+a", "command": "workbench.action.terminal.selectAll", + "when": "terminalFocus" }, +{ "key": "shift+cmd+down", "command": "workbench.action.terminal.selectToNextCommand", + "when": "terminalFocus" }, +{ "key": "shift+cmd+up", "command": "workbench.action.terminal.selectToPreviousCommand", + "when": "terminalFocus" }, +{ "key": "ctrl+shift+5", "command": "workbench.action.terminal.split", + "when": "terminalFocus" }, +{ "key": "cmd+\\", "command": "workbench.action.terminal.split", + "when": "terminalFocus" }, +{ "key": "alt+cmd+c", "command": "workbench.action.terminal.toggleFindCaseSensitive", + "when": "terminalFindWidgetFocused" }, +{ "key": "alt+cmd+c", "command": "workbench.action.terminal.toggleFindCaseSensitiveTerminalFocus", + "when": "terminalFocus" }, +{ "key": "alt+cmd+r", "command": "workbench.action.terminal.toggleFindRegex", + "when": "terminalFindWidgetFocused" }, +{ "key": "alt+cmd+r", "command": "workbench.action.terminal.toggleFindRegexTerminalFocus", + "when": "terminalFocus" }, +{ "key": "alt+cmd+w", "command": "workbench.action.terminal.toggleFindWholeWord", + "when": "terminalFindWidgetFocused" }, +{ "key": "alt+cmd+w", "command": "workbench.action.terminal.toggleFindWholeWordTerminalFocus", + "when": "terminalFocus" }, +{ "key": "ctrl+`", "command": "workbench.action.terminal.toggleTerminal" }, +{ "key": "alt+cmd+0", "command": "workbench.action.toggleEditorGroupLayout" }, +{ "key": "ctrl+cmd+f", "command": "workbench.action.toggleFullScreen" }, +{ "key": "cmd+j", "command": "workbench.action.togglePanel" }, +{ "key": "cmd+b", "command": "workbench.action.toggleSidebarVisibility" }, +{ "key": "ctrl+cmd+w", "command": "workbench.action.toggleTabsVisibility" }, +{ "key": "cmd+k z", "command": "workbench.action.toggleZenMode" }, +{ "key": "cmd+numpad_add", "command": "workbench.action.zoomIn" }, +{ "key": "shift+cmd+=", "command": "workbench.action.zoomIn" }, +{ "key": "cmd+=", "command": "workbench.action.zoomIn" }, +{ "key": "cmd+numpad_subtract", "command": "workbench.action.zoomOut" }, +{ "key": "shift+cmd+-", "command": "workbench.action.zoomOut" }, +{ "key": "cmd+-", "command": "workbench.action.zoomOut" }, +{ "key": "cmd+numpad0", "command": "workbench.action.zoomReset" }, +{ "key": "shift+cmd+m", "command": "workbench.actions.view.problems" }, +{ "key": "shift+cmd+y", "command": "workbench.debug.action.toggleRepl" }, +{ "key": "cmd+k cmd+m", "command": "workbench.extensions.action.showRecommendedKeymapExtensions" }, +{ "key": "cmd+k c", "command": "workbench.files.action.compareWithClipboard" }, +{ "key": "cmd+k d", "command": "workbench.files.action.compareWithSaved" }, +{ "key": "cmd+k e", "command": "workbench.files.action.focusOpenEditorsView", + "when": "workbench.explorer.openEditorsView.active" }, +{ "key": "shift+cmd+d", "command": "workbench.view.debug" }, +{ "key": "shift+cmd+e", "command": "workbench.view.explorer" }, +{ "key": "shift+cmd+x", "command": "workbench.view.extensions" }, +{ "key": "ctrl+shift+g", "command": "workbench.view.scm" }, +{ "key": "shift+cmd+f", "command": "workbench.view.search", + "when": "!searchViewletVisible" }, +{ "key": "escape", "command": "breadcrumbs.selectEditor", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "f11", "command": "workbench.action.debug.stepInto", + "when": "inDebugMode" }, +{ "key": "cmd+k", "command": "workbench.action.terminal.clear", + "when": "terminalFocus" }, +{ "key": "enter", "command": "debug.renameWatchExpression", + "when": "watchExpressionsFocused" }, +{ "key": "enter", "command": "debug.setVariable", + "when": "variablesFocused" }, +{ "key": "space", "command": "debug.toggleBreakpoint", + "when": "breakpointsFocused && !inputFocus" }, +{ "key": "cmd+backspace", "command": "deleteFile", + "when": "explorerViewletVisible && filesExplorerFocus && !config.files.enableTrash && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "alt+cmd+backspace", "command": "deleteFile", + "when": "config.files.enableTrash && explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "escape", "command": "filesExplorer.cancelCut", + "when": "explorerResourceCut && explorerViewletVisible && filesExplorerFocus && !inputFocus" }, +{ "key": "cmd+c", "command": "filesExplorer.copy", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !inputFocus" }, +{ "key": "cmd+x", "command": "filesExplorer.cut", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !inputFocus" }, +{ "key": "cmd+v", "command": "filesExplorer.paste", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceReadonly && !inputFocus" }, +{ "key": "cmd+backspace", "command": "moveFileToTrash", + "when": "config.files.enableTrash && explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "enter", "command": "renameFile", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "shift+escape", "command": "closeReferenceSearch", + "when": "referenceSearchVisible && !config.editor.stablePeek" }, +{ "key": "escape", "command": "closeReferenceSearch", + "when": "referenceSearchVisible && !config.editor.stablePeek" }, +{ "key": "f4", "command": "goToNextReference", + "when": "referenceSearchVisible" }, +{ "key": "shift+f4", "command": "goToPreviousReference", + "when": "referenceSearchVisible" }, +{ "key": "escape", "command": "notifications.hideList", + "when": "notificationCenterVisible" }, +{ "key": "escape", "command": "notifications.hideToasts", + "when": "notificationToastsVisible" }, +{ "key": "ctrl+-", "command": "workbench.action.quickInputBack", + "when": "inQuickOpen" }, +{ "key": "ctrl+tab", "command": "workbench.action.quickOpenNavigateNextInEditorPicker", + "when": "inEditorsPicker && inQuickOpen" }, +{ "key": "cmd+p", "command": "workbench.action.quickOpenNavigateNextInFilePicker", + "when": "inFilesPicker && inQuickOpen" }, +{ "key": "ctrl+r", "command": "workbench.action.quickOpenNavigateNextInRecentFilesPicker", + "when": "inQuickOpen && inRecentFilesPicker" }, +{ "key": "ctrl+q", "command": "workbench.action.quickOpenNavigateNextInViewPicker", + "when": "inQuickOpen && inViewsPicker" }, +{ "key": "ctrl+shift+tab", "command": "workbench.action.quickOpenNavigatePreviousInEditorPicker", + "when": "inEditorsPicker && inQuickOpen" }, +{ "key": "shift+cmd+p", "command": "workbench.action.quickOpenNavigatePreviousInFilePicker", + "when": "inFilesPicker && inQuickOpen" }, +{ "key": "ctrl+shift+r", "command": "workbench.action.quickOpenNavigatePreviousInRecentFilesPicker", + "when": "inQuickOpen && inRecentFilesPicker" }, +{ "key": "ctrl+shift+q", "command": "workbench.action.quickOpenNavigatePreviousInViewPicker", + "when": "inQuickOpen && inViewsPicker" }, +{ "key": "ctrl+n", "command": "workbench.action.quickOpenSelectNext", + "when": "inQuickOpen" }, +{ "key": "ctrl+p", "command": "workbench.action.quickOpenSelectPrevious", + "when": "inQuickOpen" }, +{ "key": "cmd+r", "command": "workbench.action.reloadWindow", + "when": "isDevelopment" }, +{ "key": "alt+cmd+i", "command": "workbench.action.toggleDevTools", + "when": "isDevelopment" }, +{ "key": "cmd+f4", "command": "extension.node-debug.pickLoadedScript", + "when": "debugType == 'node'" }, +{ "key": "cmd+f4", "command": "extension.node-debug.pickLoadedScript", + "when": "debugType == 'node2'" }, +{ "key": "shift+cmd+v", "command": "markdown.showPreview", + "when": "editorLangId == 'markdown'" }, +{ "key": "shift+alt+f12", "command": "references-view.find", + "when": "editorHasReferenceProvider" }, +{ "key": "f10", "command": "extension.node-debug.startWithStopOnEntry", + "when": "!inDebugMode && debugConfigurationType == 'node'" }, +{ "key": "cmd+k v", "command": "markdown.showPreviewToSide", + "when": "editorLangId == 'markdown'" }, +{ "key": "f4", "command": "references-view.next", + "when": "reference-list.hasResult" }, +{ "key": "f11", "command": "extension.node-debug.startWithStopOnEntry", + "when": "!inDebugMode && debugConfigurationType == 'node'" }, +{ "key": "shift+f4", "command": "references-view.prev", + "when": "reference-list.hasResult" } +] \ No newline at end of file diff --git a/build/keybindings/doc.keybindings.win.json b/build/keybindings/doc.keybindings.win.json new file mode 100644 index 0000000000000000000000000000000000000000..402732bcea9e20dc3aa8edbfa68a89410497d9fb --- /dev/null +++ b/build/keybindings/doc.keybindings.win.json @@ -0,0 +1,902 @@ +[ +{ "key": "escape escape", "command": "workbench.action.exitZenMode", + "when": "inZenMode" }, +{ "key": "shift+escape", "command": "closeReferenceSearchEditor", + "when": "inReferenceSearchEditor && !config.editor.stablePeek" }, +{ "key": "escape", "command": "closeReferenceSearchEditor", + "when": "inReferenceSearchEditor && !config.editor.stablePeek" }, +{ "key": "shift+escape", "command": "cancelSelection", + "when": "editorHasSelection && textInputFocus" }, +{ "key": "escape", "command": "cancelSelection", + "when": "editorHasSelection && textInputFocus" }, +{ "key": "ctrl+end", "command": "cursorBottom", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+end", "command": "cursorBottomSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+alt+down", "command": "cursorColumnSelectDown", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+alt+left", "command": "cursorColumnSelectLeft", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+alt+pagedown", "command": "cursorColumnSelectPageDown", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+alt+pageup", "command": "cursorColumnSelectPageUp", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+alt+right", "command": "cursorColumnSelectRight", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+alt+up", "command": "cursorColumnSelectUp", + "when": "textInputFocus" }, +{ "key": "down", "command": "cursorDown", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+down", "command": "cursorDownSelect", + "when": "textInputFocus" }, +{ "key": "shift+down", "command": "cursorDownSelect", + "when": "textInputFocus" }, +{ "key": "end", "command": "cursorEnd", + "when": "textInputFocus" }, +{ "key": "shift+end", "command": "cursorEndSelect", + "when": "textInputFocus" }, +{ "key": "home", "command": "cursorHome", + "when": "textInputFocus" }, +{ "key": "shift+home", "command": "cursorHomeSelect", + "when": "textInputFocus" }, +{ "key": "left", "command": "cursorLeft", + "when": "textInputFocus" }, +{ "key": "shift+left", "command": "cursorLeftSelect", + "when": "textInputFocus" }, +{ "key": "pagedown", "command": "cursorPageDown", + "when": "textInputFocus" }, +{ "key": "shift+pagedown", "command": "cursorPageDownSelect", + "when": "textInputFocus" }, +{ "key": "pageup", "command": "cursorPageUp", + "when": "textInputFocus" }, +{ "key": "shift+pageup", "command": "cursorPageUpSelect", + "when": "textInputFocus" }, +{ "key": "right", "command": "cursorRight", + "when": "textInputFocus" }, +{ "key": "shift+right", "command": "cursorRightSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+home", "command": "cursorTop", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+home", "command": "cursorTopSelect", + "when": "textInputFocus" }, +{ "key": "up", "command": "cursorUp", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+up", "command": "cursorUpSelect", + "when": "textInputFocus" }, +{ "key": "shift+up", "command": "cursorUpSelect", + "when": "textInputFocus" }, +{ "key": "shift+backspace", "command": "deleteLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "backspace", "command": "deleteLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "delete", "command": "deleteRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+a", "command": "editor.action.selectAll", + "when": "textInputFocus" }, +{ "key": "ctrl+l", "command": "expandLineSelection", + "when": "textInputFocus" }, +{ "key": "shift+tab", "command": "outdent", + "when": "editorTextFocus && !editorReadonly && !editorTabMovesFocus" }, +{ "key": "ctrl+shift+z", "command": "redo", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+y", "command": "redo", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+down", "command": "scrollLineDown", + "when": "textInputFocus" }, +{ "key": "ctrl+up", "command": "scrollLineUp", + "when": "textInputFocus" }, +{ "key": "alt+pagedown", "command": "scrollPageDown", + "when": "textInputFocus" }, +{ "key": "alt+pageup", "command": "scrollPageUp", + "when": "textInputFocus" }, +{ "key": "tab", "command": "tab", + "when": "editorTextFocus && !editorReadonly && !editorTabMovesFocus" }, +{ "key": "ctrl+z", "command": "undo", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "shift+escape", "command": "removeSecondaryCursors", + "when": "editorHasMultipleSelections && textInputFocus" }, +{ "key": "escape", "command": "removeSecondaryCursors", + "when": "editorHasMultipleSelections && textInputFocus" }, +{ "key": "ctrl+f", "command": "actions.find" }, +{ "key": "enter", "command": "breakpointWidget.action.acceptInput", + "when": "breakpointWidgetVisible && inBreakpointWidget" }, +{ "key": "shift+escape", "command": "closeBreakpointWidget", + "when": "breakpointWidgetVisible && textInputFocus" }, +{ "key": "escape", "command": "closeBreakpointWidget", + "when": "breakpointWidgetVisible && textInputFocus" }, +{ "key": "shift+escape", "command": "closeReviewPanel", + "when": "reviewPanelVisible" }, +{ "key": "escape", "command": "closeReviewPanel", + "when": "reviewPanelVisible" }, +{ "key": "ctrl+u", "command": "cursorUndo", + "when": "textInputFocus" }, +{ "key": "ctrl+right", "command": "cursorWordEndRight", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+right", "command": "cursorWordEndRightSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+left", "command": "cursorWordStartLeft", + "when": "textInputFocus" }, +{ "key": "ctrl+shift+left", "command": "cursorWordStartLeftSelect", + "when": "textInputFocus" }, +{ "key": "ctrl+backspace", "command": "deleteWordLeft", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+delete", "command": "deleteWordRight", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+k ctrl+c", "command": "editor.action.addCommentLine", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+d", "command": "editor.action.addSelectionToNextFindMatch", + "when": "editorFocus" }, +{ "key": "shift+alt+.", "command": "editor.action.autoFix", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+alt+a", "command": "editor.action.blockComment", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+f2", "command": "editor.action.changeAll", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+insert", "command": "editor.action.clipboardCopyAction", + "when": "textInputFocus" }, +{ "key": "ctrl+c", "command": "editor.action.clipboardCopyAction", + "when": "textInputFocus" }, +{ "key": "shift+delete", "command": "editor.action.clipboardCutAction", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+x", "command": "editor.action.clipboardCutAction", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "shift+insert", "command": "editor.action.clipboardPasteAction", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+v", "command": "editor.action.clipboardPasteAction", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "ctrl+/", "command": "editor.action.commentLine", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+alt+down", "command": "editor.action.copyLinesDownAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+alt+up", "command": "editor.action.copyLinesUpAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+k ctrl+k", "command": "editor.action.defineKeybinding", + "when": "editorTextFocus && !editorReadonly && editorLangId == 'jsonc'" }, +{ "key": "ctrl+shift+k", "command": "editor.action.deleteLines", + "when": "textInputFocus && !editorReadonly" }, +{ "key": "f7", "command": "editor.action.diffReview.next", + "when": "isInDiffEditor" }, +{ "key": "shift+f7", "command": "editor.action.diffReview.prev", + "when": "isInDiffEditor" }, +{ "key": "alt+f3", "command": "editor.action.dirtydiff.next", + "when": "editorTextFocus" }, +{ "key": "shift+alt+f3", "command": "editor.action.dirtydiff.previous", + "when": "editorTextFocus" }, +{ "key": "ctrl+f", "command": "editor.action.extensioneditor.showfind", + "when": "activeEditor == 'workbench.editor.extension'" }, +{ "key": "shift+alt+f", "command": "editor.action.formatDocument", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+k ctrl+f", "command": "editor.action.formatSelection", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+f12", "command": "editor.action.goToImplementation", + "when": "editorHasImplementationProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "ctrl+shift+.", "command": "editor.action.inPlaceReplace.down", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+,", "command": "editor.action.inPlaceReplace.up", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+]", "command": "editor.action.indentLines", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+alt+up", "command": "editor.action.insertCursorAbove", + "when": "editorTextFocus" }, +{ "key": "shift+alt+i", "command": "editor.action.insertCursorAtEndOfEachLineSelected", + "when": "editorTextFocus" }, +{ "key": "ctrl+alt+down", "command": "editor.action.insertCursorBelow", + "when": "editorTextFocus" }, +{ "key": "ctrl+enter", "command": "editor.action.insertLineAfter", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+enter", "command": "editor.action.insertLineBefore", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+\\", "command": "editor.action.jumpToBracket", + "when": "editorTextFocus" }, +{ "key": "alt+f8", "command": "editor.action.marker.next", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "f8", "command": "editor.action.marker.nextInFiles", + "when": "editorFocus && !editorReadonly" }, +{ "key": "shift+alt+f8", "command": "editor.action.marker.prev", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "shift+f8", "command": "editor.action.marker.prevInFiles", + "when": "editorFocus && !editorReadonly" }, +{ "key": "alt+down", "command": "editor.action.moveLinesDownAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "alt+up", "command": "editor.action.moveLinesUpAction", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+k ctrl+d", "command": "editor.action.moveSelectionToNextFindMatch", + "when": "editorFocus" }, +{ "key": "f3", "command": "editor.action.nextMatchFindAction", + "when": "editorFocus" }, +{ "key": "ctrl+f3", "command": "editor.action.nextSelectionMatchFindAction", + "when": "editorFocus" }, +{ "key": "shift+alt+o", "command": "editor.action.organizeImports", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+[", "command": "editor.action.outdentLines", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "alt+f12", "command": "editor.action.peekDefinition", + "when": "editorHasDefinitionProvider && editorTextFocus && !inReferenceSearchEditor && !isInEmbeddedEditor" }, +{ "key": "ctrl+shift+f12", "command": "editor.action.peekImplementation", + "when": "editorHasImplementationProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "shift+f3", "command": "editor.action.previousMatchFindAction", + "when": "editorFocus" }, +{ "key": "ctrl+shift+f3", "command": "editor.action.previousSelectionMatchFindAction", + "when": "editorFocus" }, +{ "key": "ctrl+.", "command": "editor.action.quickFix", + "when": "editorHasCodeActionsProvider && editorTextFocus && !editorReadonly" }, +{ "key": "ctrl+shift+r", "command": "editor.action.refactor", + "when": "editorHasCodeActionsProvider && editorTextFocus && !editorReadonly" }, +{ "key": "shift+f12", "command": "editor.action.referenceSearch.trigger", + "when": "editorHasReferenceProvider && editorTextFocus && !inReferenceSearchEditor && !isInEmbeddedEditor" }, +{ "key": "ctrl+k ctrl+u", "command": "editor.action.removeCommentLine", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "f2", "command": "editor.action.rename", + "when": "editorHasRenameProvider && editorTextFocus && !editorReadonly" }, +{ "key": "f12", "command": "editor.action.revealDefinition", + "when": "editorHasDefinitionProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "ctrl+k f12", "command": "editor.action.revealDefinitionAside", + "when": "editorHasDefinitionProvider && editorTextFocus && !isInEmbeddedEditor" }, +{ "key": "ctrl+shift+l", "command": "editor.action.selectHighlights", + "when": "editorFocus" }, +{ "key": "alt+f1", "command": "editor.action.showAccessibilityHelp", + "when": "editorFocus" }, +{ "key": "shift+f10", "command": "editor.action.showContextMenu", + "when": "textInputFocus" }, +{ "key": "ctrl+k ctrl+i", "command": "editor.action.showHover", + "when": "editorTextFocus" }, +{ "key": "shift+alt+right", "command": "editor.action.smartSelect.expand", + "when": "editorTextFocus" }, +{ "key": "shift+alt+left", "command": "editor.action.smartSelect.shrink", + "when": "editorTextFocus" }, +{ "key": "ctrl+h", "command": "editor.action.startFindReplaceAction" }, +{ "key": "ctrl+m", "command": "editor.action.toggleTabFocusMode" }, +{ "key": "alt+z", "command": "editor.action.toggleWordWrap" }, +{ "key": "ctrl+shift+space", "command": "editor.action.triggerParameterHints", + "when": "editorHasSignatureHelpProvider && editorTextFocus" }, +{ "key": "ctrl+space", "command": "editor.action.triggerSuggest", + "when": "editorHasCompletionItemProvider && textInputFocus && !editorReadonly" }, +{ "key": "ctrl+k ctrl+x", "command": "editor.action.trimTrailingWhitespace", + "when": "editorTextFocus && !editorReadonly" }, +{ "key": "escape", "command": "editor.action.webvieweditor.hideFind", + "when": "webviewFindWidgetVisible && !editorFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "escape", "command": "editor.action.webvieweditor.hideFind", + "when": "webviewFindWidgetVisible && !editorFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "ctrl+a", "command": "editor.action.webvieweditor.selectAll", + "when": "!editorFocus && !inputFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "ctrl+a", "command": "editor.action.webvieweditor.selectAll", + "when": "!editorFocus && !inputFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "ctrl+f", "command": "editor.action.webvieweditor.showFind", + "when": "!editorFocus && activeEditor == 'workbench.editor.htmlPreviewPart'" }, +{ "key": "ctrl+f", "command": "editor.action.webvieweditor.showFind", + "when": "!editorFocus && activeEditor == 'WebviewEditor'" }, +{ "key": "f7", "command": "editor.action.wordHighlight.next", + "when": "editorTextFocus && hasWordHighlights" }, +{ "key": "shift+f7", "command": "editor.action.wordHighlight.prev", + "when": "editorTextFocus && hasWordHighlights" }, +{ "key": "ctrl+k ctrl+i", "command": "editor.debug.action.showDebugHover", + "when": "editorTextFocus && inDebugMode" }, +{ "key": "f9", "command": "editor.debug.action.toggleBreakpoint", + "when": "editorTextFocus" }, +{ "key": "tab", "command": "editor.emmet.action.expandAbbreviation", + "when": "config.emmet.triggerExpansionOnTab && editorTextFocus && !editorReadonly && !editorTabMovesFocus" }, +{ "key": "ctrl+shift+[", "command": "editor.fold", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+0", "command": "editor.foldAll", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+/", "command": "editor.foldAllBlockComments", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+8", "command": "editor.foldAllMarkerRegions", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+1", "command": "editor.foldLevel1", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+2", "command": "editor.foldLevel2", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+3", "command": "editor.foldLevel3", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+4", "command": "editor.foldLevel4", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+5", "command": "editor.foldLevel5", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+6", "command": "editor.foldLevel6", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+7", "command": "editor.foldLevel7", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+[", "command": "editor.foldRecursively", + "when": "editorTextFocus" }, +{ "key": "ctrl+shift+]", "command": "editor.unfold", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+j", "command": "editor.unfoldAll", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+9", "command": "editor.unfoldAllMarkerRegions", + "when": "editorTextFocus" }, +{ "key": "ctrl+k ctrl+]", "command": "editor.unfoldRecursively", + "when": "editorTextFocus" }, +{ "key": "tab", "command": "insertSnippet", + "when": "editorTextFocus && hasSnippetCompletions && !editorTabMovesFocus && !inSnippetMode" }, +{ "key": "ctrl+enter", "command": "openReferenceToSide", + "when": "referenceSearchTreeFocused && referenceSearchVisible" }, +{ "key": "enter", "command": "repl.action.acceptInput", + "when": "inDebugRepl && textInputFocus" }, +{ "key": "escape", "command": "settings.action.clearSearchResults", + "when": "inSettingsSearch" }, +{ "key": "ctrl+.", "command": "settings.action.editFocusedSetting", + "when": "inSettingsSearch" }, +{ "key": "enter", "command": "settings.action.focusNextSetting", + "when": "inSettingsSearch" }, +{ "key": "shift+enter", "command": "settings.action.focusPreviousSetting", + "when": "inSettingsSearch" }, +{ "key": "down", "command": "settings.action.focusSettingsFile", + "when": "inSettingsSearch && !suggestWidgetVisible" }, +{ "key": "ctrl+f", "command": "settings.action.search", + "when": "inSettingsEditor" }, +{ "key": "alt+f5", "command": "workbench.action.editor.nextChange", + "when": "editorTextFocus" }, +{ "key": "shift+alt+f5", "command": "workbench.action.editor.previousChange", + "when": "editorTextFocus" }, +{ "key": "shift+escape", "command": "closeFindWidget", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "escape", "command": "closeFindWidget", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "ctrl+alt+enter", "command": "editor.action.replaceAll", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "ctrl+shift+1", "command": "editor.action.replaceOne", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "alt+enter", "command": "editor.action.selectAllMatches", + "when": "editorFocus && findWidgetVisible" }, +{ "key": "alt+c", "command": "toggleFindCaseSensitive", + "when": "editorFocus" }, +{ "key": "alt+l", "command": "toggleFindInSelection", + "when": "editorFocus" }, +{ "key": "alt+r", "command": "toggleFindRegex", + "when": "editorFocus" }, +{ "key": "alt+w", "command": "toggleFindWholeWord", + "when": "editorFocus" }, +{ "key": "tab", "command": "jumpToNextSnippetPlaceholder", + "when": "editorTextFocus && hasNextTabstop && inSnippetMode" }, +{ "key": "shift+tab", "command": "jumpToPrevSnippetPlaceholder", + "when": "editorTextFocus && hasPrevTabstop && inSnippetMode" }, +{ "key": "escape", "command": "leaveEditorMessage", + "when": "messageVisible" }, +{ "key": "shift+escape", "command": "leaveSnippet", + "when": "editorTextFocus && inSnippetMode" }, +{ "key": "escape", "command": "leaveSnippet", + "when": "editorTextFocus && inSnippetMode" }, +{ "key": "shift+escape", "command": "closeDirtyDiff", + "when": "dirtyDiffVisible" }, +{ "key": "escape", "command": "closeDirtyDiff", + "when": "dirtyDiffVisible" }, +{ "key": "shift+escape", "command": "closeMarkersNavigation", + "when": "editorFocus && markersNavigationVisible" }, +{ "key": "escape", "command": "closeMarkersNavigation", + "when": "editorFocus && markersNavigationVisible" }, +{ "key": "f4", "command": "goToNextReferenceFromEmbeddedEditor", + "when": "inReferenceSearchEditor" }, +{ "key": "shift+f4", "command": "goToPreviousReferenceFromEmbeddedEditor", + "when": "inReferenceSearchEditor" }, +{ "key": "shift+escape", "command": "closeParameterHints", + "when": "editorFocus && parameterHintsVisible" }, +{ "key": "escape", "command": "closeParameterHints", + "when": "editorFocus && parameterHintsVisible" }, +{ "key": "alt+down", "command": "showNextParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "down", "command": "showNextParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "alt+up", "command": "showPrevParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "up", "command": "showPrevParameterHint", + "when": "editorFocus && parameterHintsMultipleSignatures && parameterHintsVisible" }, +{ "key": "tab", "command": "acceptSelectedSuggestion", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "enter", "command": "acceptSelectedSuggestionOnEnter", + "when": "acceptSuggestionOnEnter && suggestWidgetVisible && suggestionMakesTextEdit && textInputFocus" }, +{ "key": "shift+escape", "command": "hideSuggestWidget", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "escape", "command": "hideSuggestWidget", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "tab", "command": "insertBestCompletion", + "when": "atEndOfWord && !hasOtherSuggestions && !inSnippetMode && !suggestWidgetVisible && config.editor.tabCompletion == 'on'" }, +{ "key": "tab", "command": "insertNextSuggestion", + "when": "hasOtherSuggestions && textInputFocus && !inSnippetMode && !suggestWidgetVisible && config.editor.tabCompletion == 'on'" }, +{ "key": "shift+tab", "command": "insertPrevSuggestion", + "when": "hasOtherSuggestions && textInputFocus && !inSnippetMode && !suggestWidgetVisible && config.editor.tabCompletion == 'on'" }, +{ "key": "ctrl+pagedown", "command": "selectNextPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "pagedown", "command": "selectNextPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+down", "command": "selectNextSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "down", "command": "selectNextSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+pageup", "command": "selectPrevPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "pageup", "command": "selectPrevPageSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+up", "command": "selectPrevSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "up", "command": "selectPrevSuggestion", + "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+space", "command": "toggleSuggestionDetails", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "ctrl+alt+space", "command": "toggleSuggestionFocus", + "when": "suggestWidgetVisible && textInputFocus" }, +{ "key": "enter", "command": "acceptRenameInput", + "when": "editorFocus && renameInputVisible" }, +{ "key": "shift+escape", "command": "cancelRenameInput", + "when": "editorFocus && renameInputVisible" }, +{ "key": "escape", "command": "cancelRenameInput", + "when": "editorFocus && renameInputVisible" }, +{ "key": "ctrl+shift+;", "command": "breadcrumbs.focus", + "when": "breadcrumbsPossible" }, +{ "key": "ctrl+shift+.", "command": "breadcrumbs.focusAndSelect", + "when": "breadcrumbsPossible" }, +{ "key": "ctrl+right", "command": "breadcrumbs.focusNext", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "right", "command": "breadcrumbs.focusNext", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "ctrl+left", "command": "breadcrumbs.focusPrevious", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "left", "command": "breadcrumbs.focusPrevious", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "ctrl+enter", "command": "breadcrumbs.revealFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "space", "command": "breadcrumbs.revealFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "ctrl+enter", "command": "breadcrumbs.revealFocusedFromTreeAside", + "when": "breadcrumbsActive && breadcrumbsVisible && listFocus && !inputFocus" }, +{ "key": "down", "command": "breadcrumbs.selectFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "enter", "command": "breadcrumbs.selectFocused", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "ctrl+shift+.", "command": "breadcrumbs.toggleToOn", + "when": "!config.breadcrumbs.enabled" }, +{ "key": "shift+escape", "command": "closeAccessibilityHelp", + "when": "accessibilityHelpWidgetVisible && editorFocus" }, +{ "key": "escape", "command": "closeAccessibilityHelp", + "when": "accessibilityHelpWidgetVisible && editorFocus" }, +{ "key": "escape", "command": "closeReplaceInFilesWidget", + "when": "replaceInputBoxFocus && searchViewletVisible" }, +{ "key": "shift+alt+c", "command": "copyFilePath", + "when": "!editorFocus" }, +{ "key": "ctrl+k ctrl+shift+c", "command": "copyRelativeFilePath", + "when": "!editorFocus" }, +{ "key": "alt+enter", "command": "debug.openBreakpointToSide", + "when": "breakpointsFocused" }, +{ "key": "ctrl+enter", "command": "debug.openBreakpointToSide", + "when": "breakpointsFocused" }, +{ "key": "delete", "command": "debug.removeBreakpoint", + "when": "breakpointsFocused && !breakpointSelected" }, +{ "key": "delete", "command": "debug.removeWatchExpression", + "when": "watchExpressionsFocused && !expressionSelected" }, +{ "key": "shift+f9", "command": "editor.debug.action.toggleInlineBreakpoint", + "when": "editorTextFocus" }, +{ "key": "ctrl+enter", "command": "explorer.openToSide", + "when": "explorerViewletFocus && explorerViewletVisible && !inputFocus" }, +{ "key": "shift+alt+f", "command": "filesExplorer.findInFolder", + "when": "explorerResourceIsFolder && explorerViewletVisible && filesExplorerFocus && !inputFocus && resourceScheme == 'file'" }, +{ "key": "alt+down", "command": "history.showNext", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "down", "command": "history.showNext", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "alt+up", "command": "history.showPrevious", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "up", "command": "history.showPrevious", + "when": "historyNavigationEnabled && historyNavigationWidget" }, +{ "key": "ctrl+down", "command": "problems.action.focusProblemsFromFilter", + "when": "problemsFilterFocus" }, +{ "key": "ctrl+c", "command": "problems.action.copy", + "when": "problemFocus" }, +{ "key": "ctrl+f", "command": "problems.action.focusFilter", + "when": "problemsViewFocus" }, +{ "key": "escape", "command": "keybindings.editor.clearSearchResults", + "when": "inKeybindings && inKeybindingsSearch" }, +{ "key": "ctrl+c", "command": "keybindings.editor.copyKeybindingEntry", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "ctrl+k ctrl+k", "command": "keybindings.editor.defineKeybinding", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "ctrl+k ctrl+e", "command": "keybindings.editor.defineWhenExpression", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "down", "command": "keybindings.editor.focusKeybindings", + "when": "inKeybindings && inKeybindingsSearch" }, +{ "key": "alt+k", "command": "keybindings.editor.recordSearchKeys", + "when": "inKeybindings && inKeybindingsSearch" }, +{ "key": "delete", "command": "keybindings.editor.removeKeybinding", + "when": "inKeybindings && keybindingFocus" }, +{ "key": "ctrl+f", "command": "keybindings.editor.searchKeybindings", + "when": "inKeybindings" }, +{ "key": "alt+p", "command": "keybindings.editor.toggleSortByPrecedence", + "when": "inKeybindings" }, +{ "key": "escape", "command": "list.clear", + "when": "listFocus && listHasSelectionOrFocus && !inputFocus" }, +{ "key": "left", "command": "list.collapse", + "when": "listFocus && !inputFocus" }, +{ "key": "right", "command": "list.expand", + "when": "listFocus && !inputFocus" }, +{ "key": "shift+down", "command": "list.expandSelectionDown", + "when": "listFocus && listSupportsMultiselect && !inputFocus" }, +{ "key": "shift+up", "command": "list.expandSelectionUp", + "when": "listFocus && listSupportsMultiselect && !inputFocus" }, +{ "key": "down", "command": "list.focusDown", + "when": "listFocus && !inputFocus" }, +{ "key": "home", "command": "list.focusFirst", + "when": "listFocus && !inputFocus" }, +{ "key": "end", "command": "list.focusLast", + "when": "listFocus && !inputFocus" }, +{ "key": "pagedown", "command": "list.focusPageDown", + "when": "listFocus && !inputFocus" }, +{ "key": "pageup", "command": "list.focusPageUp", + "when": "listFocus && !inputFocus" }, +{ "key": "up", "command": "list.focusUp", + "when": "listFocus && !inputFocus" }, +{ "key": "enter", "command": "list.select", + "when": "listFocus && !inputFocus" }, +{ "key": "ctrl+a", "command": "list.selectAll", + "when": "listFocus && listSupportsMultiselect && !inputFocus" }, +{ "key": "space", "command": "list.toggleExpand", + "when": "listFocus && !inputFocus" }, +{ "key": "delete", "command": "notification.clear", + "when": "notificationFocus" }, +{ "key": "left", "command": "notification.collapse", + "when": "notificationFocus" }, +{ "key": "right", "command": "notification.expand", + "when": "notificationFocus" }, +{ "key": "enter", "command": "notification.toggle", + "when": "notificationFocus" }, +{ "key": "space", "command": "notification.toggle", + "when": "notificationFocus" }, +{ "key": "home", "command": "notifications.focusFirstToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "pageup", "command": "notifications.focusFirstToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "end", "command": "notifications.focusLastToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "pagedown", "command": "notifications.focusLastToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "down", "command": "notifications.focusNextToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "up", "command": "notifications.focusPreviousToast", + "when": "notificationFocus && notificationToastsVisible" }, +{ "key": "ctrl+enter", "command": "problems.action.openToSide", + "when": "problemFocus" }, +{ "key": "ctrl+.", "command": "problems.action.showQuickFixes", + "when": "problemFocus" }, +{ "key": "shift+alt+r", "command": "revealFileInOS", + "when": "!editorFocus" }, +{ "key": "ctrl+enter", "command": "scm.acceptInput", + "when": "scmRepository" }, +{ "key": "escape", "command": "search.action.cancel", + "when": "listFocus && searchViewletVisible && !inputFocus" }, +{ "key": "ctrl+c", "command": "search.action.copyMatch", + "when": "fileMatchOrMatchFocus" }, +{ "key": "shift+alt+c", "command": "search.action.copyPath", + "when": "fileMatchOrFolderMatchFocus" }, +{ "key": "f4", "command": "search.action.focusNextSearchResult", + "when": "hasSearchResult" }, +{ "key": "shift+f4", "command": "search.action.focusPreviousSearchResult", + "when": "hasSearchResult" }, +{ "key": "ctrl+up", "command": "search.action.focusSearchFromResults", + "when": "firstMatchFocus && searchViewletVisible" }, +{ "key": "ctrl+enter", "command": "search.action.openResultToSide", + "when": "fileMatchOrMatchFocus && searchViewletVisible" }, +{ "key": "delete", "command": "search.action.remove", + "when": "fileMatchOrMatchFocus && searchViewletVisible" }, +{ "key": "ctrl+shift+1", "command": "search.action.replace", + "when": "matchFocus && replaceActive && searchViewletVisible" }, +{ "key": "ctrl+alt+enter", "command": "search.action.replaceAll", + "when": "replaceActive && searchViewletVisible && !findWidgetVisible" }, +{ "key": "ctrl+shift+enter", "command": "search.action.replaceAllInFile", + "when": "fileMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "ctrl+shift+1", "command": "search.action.replaceAllInFile", + "when": "fileMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "ctrl+shift+enter", "command": "search.action.replaceAllInFolder", + "when": "folderMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "ctrl+shift+1", "command": "search.action.replaceAllInFolder", + "when": "folderMatchFocus && replaceActive && searchViewletVisible" }, +{ "key": "ctrl+down", "command": "search.focus.nextInputBox", + "when": "inputBoxFocus && searchViewletVisible" }, +{ "key": "ctrl+up", "command": "search.focus.previousInputBox", + "when": "inputBoxFocus && searchViewletVisible && !searchInputBoxFocus" }, +{ "key": "down", "command": "settings.action.focusSettingsFromSearch", + "when": "inSettingsSearch && !suggestWidgetVisible" }, +{ "key": "enter", "command": "settings.action.focusSettingsList", + "when": "inSettingsEditor && settingsTocRowFocus" }, +{ "key": "shift+f9", "command": "settings.action.showContextMenu", + "when": "inSettingsEditor" }, +{ "key": "alt+c", "command": "toggleSearchCaseSensitive", + "when": "searchViewletFocus && searchViewletVisible && !fileMatchOrFolderMatchFocus" }, +{ "key": "alt+r", "command": "toggleSearchRegex", + "when": "searchViewletFocus && searchViewletVisible" }, +{ "key": "alt+w", "command": "toggleSearchWholeWord", + "when": "searchViewletFocus && searchViewletVisible" }, +{ "key": "ctrl+w", "command": "workbench.action.closeActiveEditor" }, +{ "key": "ctrl+f4", "command": "workbench.action.closeActiveEditor" }, +{ "key": "ctrl+k ctrl+w", "command": "workbench.action.closeAllEditors" }, +{ "key": "ctrl+k ctrl+shift+w", "command": "workbench.action.closeAllGroups" }, +{ "key": "ctrl+k w", "command": "workbench.action.closeEditorsInGroup" }, +{ "key": "ctrl+k f", "command": "workbench.action.closeFolder" }, +{ "key": "ctrl+w", "command": "workbench.action.closeGroup", + "when": "activeEditorGroupEmpty && multipleEditorGroups" }, +{ "key": "ctrl+f4", "command": "workbench.action.closeGroup", + "when": "activeEditorGroupEmpty && multipleEditorGroups" }, +{ "key": "shift+escape", "command": "workbench.action.closeQuickOpen", + "when": "inQuickOpen" }, +{ "key": "escape", "command": "workbench.action.closeQuickOpen", + "when": "inQuickOpen" }, +{ "key": "ctrl+k u", "command": "workbench.action.closeUnmodifiedEditors" }, +{ "key": "ctrl+shift+w", "command": "workbench.action.closeWindow" }, +{ "key": "ctrl+w", "command": "workbench.action.closeWindow", + "when": "!editorIsOpen && !multipleEditorGroups" }, +{ "key": "alt+f5", "command": "workbench.action.compareEditor.nextChange", + "when": "textCompareEditorVisible" }, +{ "key": "shift+alt+f5", "command": "workbench.action.compareEditor.previousChange", + "when": "textCompareEditorVisible" }, +{ "key": "f5", "command": "workbench.action.debug.continue", + "when": "inDebugMode" }, +{ "key": "f6", "command": "workbench.action.debug.pause", + "when": "inDebugMode" }, +{ "key": "ctrl+shift+f5", "command": "workbench.action.debug.restart", + "when": "inDebugMode" }, +{ "key": "ctrl+f5", "command": "workbench.action.debug.run", + "when": "!inDebugMode" }, +{ "key": "f5", "command": "workbench.action.debug.start", + "when": "!inDebugMode" }, +{ "key": "shift+f11", "command": "workbench.action.debug.stepOut", + "when": "inDebugMode" }, +{ "key": "f10", "command": "workbench.action.debug.stepOver", + "when": "inDebugMode" }, +{ "key": "shift+f5", "command": "workbench.action.debug.stop", + "when": "inDebugMode" }, +{ "key": "ctrl+k m", "command": "workbench.action.editor.changeLanguageMode" }, +{ "key": "ctrl+k p", "command": "workbench.action.files.copyPathOfActiveFile" }, +{ "key": "ctrl+n", "command": "workbench.action.files.newUntitledFile" }, +{ "key": "ctrl+o", "command": "workbench.action.files.openFile" }, +{ "key": "ctrl+k ctrl+o", "command": "workbench.action.files.openFolder" }, +{ "key": "ctrl+k r", "command": "workbench.action.files.revealActiveFileInWindows" }, +{ "key": "ctrl+s", "command": "workbench.action.files.save" }, +{ "key": "ctrl+k s", "command": "workbench.action.files.saveAll" }, +{ "key": "ctrl+shift+s", "command": "workbench.action.files.saveAs" }, +{ "key": "ctrl+k ctrl+shift+s", "command": "workbench.action.files.saveWithoutFormatting" }, +{ "key": "ctrl+k o", "command": "workbench.action.files.showOpenedFileInNewWindow" }, +{ "key": "ctrl+shift+f", "command": "workbench.action.findInFiles" }, +{ "key": "ctrl+k ctrl+up", "command": "workbench.action.focusAboveGroup" }, +{ "key": "ctrl+k ctrl+down", "command": "workbench.action.focusBelowGroup" }, +{ "key": "ctrl+8", "command": "workbench.action.focusEighthEditorGroup" }, +{ "key": "ctrl+5", "command": "workbench.action.focusFifthEditorGroup" }, +{ "key": "ctrl+1", "command": "workbench.action.focusFirstEditorGroup" }, +{ "key": "ctrl+4", "command": "workbench.action.focusFourthEditorGroup" }, +{ "key": "ctrl+k ctrl+left", "command": "workbench.action.focusLeftGroup" }, +{ "key": "ctrl+k ctrl+right", "command": "workbench.action.focusRightGroup" }, +{ "key": "ctrl+2", "command": "workbench.action.focusSecondEditorGroup" }, +{ "key": "ctrl+7", "command": "workbench.action.focusSeventhEditorGroup" }, +{ "key": "ctrl+0", "command": "workbench.action.focusSideBar" }, +{ "key": "ctrl+6", "command": "workbench.action.focusSixthEditorGroup" }, +{ "key": "ctrl+3", "command": "workbench.action.focusThirdEditorGroup" }, +{ "key": "ctrl+g", "command": "workbench.action.gotoLine" }, +{ "key": "ctrl+shift+o", "command": "workbench.action.gotoSymbol" }, +{ "key": "escape", "command": "workbench.action.hideInterfaceOverview", + "when": "interfaceOverviewVisible" }, +{ "key": "down", "command": "workbench.action.interactivePlayground.arrowDown", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "up", "command": "workbench.action.interactivePlayground.arrowUp", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "pagedown", "command": "workbench.action.interactivePlayground.pageDown", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "pageup", "command": "workbench.action.interactivePlayground.pageUp", + "when": "interactivePlaygroundFocus && !editorTextFocus" }, +{ "key": "ctrl+k enter", "command": "workbench.action.keepEditor" }, +{ "key": "ctrl+k ctrl+r", "command": "workbench.action.keybindingsReference" }, +{ "key": "ctrl+9", "command": "workbench.action.lastEditorInGroup" }, +{ "key": "alt+0", "command": "workbench.action.lastEditorInGroup" }, +{ "key": "ctrl+k down", "command": "workbench.action.moveActiveEditorGroupDown" }, +{ "key": "ctrl+k left", "command": "workbench.action.moveActiveEditorGroupLeft" }, +{ "key": "ctrl+k right", "command": "workbench.action.moveActiveEditorGroupRight" }, +{ "key": "ctrl+k up", "command": "workbench.action.moveActiveEditorGroupUp" }, +{ "key": "ctrl+shift+pageup", "command": "workbench.action.moveEditorLeftInGroup" }, +{ "key": "ctrl+shift+pagedown", "command": "workbench.action.moveEditorRightInGroup" }, +{ "key": "shift+alt+1", "command": "workbench.action.moveEditorToFirstGroup" }, +{ "key": "shift+alt+9", "command": "workbench.action.moveEditorToLastGroup" }, +{ "key": "ctrl+alt+right", "command": "workbench.action.moveEditorToNextGroup" }, +{ "key": "ctrl+alt+left", "command": "workbench.action.moveEditorToPreviousGroup" }, +{ "key": "alt+left", "command": "workbench.action.navigateBack" }, +{ "key": "alt+right", "command": "workbench.action.navigateForward" }, +{ "key": "ctrl+k ctrl+q", "command": "workbench.action.navigateToLastEditLocation" }, +{ "key": "ctrl+shift+n", "command": "workbench.action.newWindow" }, +{ "key": "ctrl+pagedown", "command": "workbench.action.nextEditor" }, +{ "key": "alt+1", "command": "workbench.action.openEditorAtIndex1" }, +{ "key": "alt+2", "command": "workbench.action.openEditorAtIndex2" }, +{ "key": "alt+3", "command": "workbench.action.openEditorAtIndex3" }, +{ "key": "alt+4", "command": "workbench.action.openEditorAtIndex4" }, +{ "key": "alt+5", "command": "workbench.action.openEditorAtIndex5" }, +{ "key": "alt+6", "command": "workbench.action.openEditorAtIndex6" }, +{ "key": "alt+7", "command": "workbench.action.openEditorAtIndex7" }, +{ "key": "alt+8", "command": "workbench.action.openEditorAtIndex8" }, +{ "key": "alt+9", "command": "workbench.action.openEditorAtIndex9" }, +{ "key": "ctrl+k ctrl+s", "command": "workbench.action.openGlobalKeybindings" }, +{ "key": "ctrl+tab", "command": "workbench.action.openNextRecentlyUsedEditorInGroup" }, +{ "key": "ctrl+shift+tab", "command": "workbench.action.openPreviousRecentlyUsedEditorInGroup" }, +{ "key": "ctrl+r", "command": "workbench.action.openRecent" }, +{ "key": "ctrl+,", "command": "workbench.action.openSettings" }, +{ "key": "ctrl+shift+u", "command": "workbench.action.output.toggleOutput" }, +{ "key": "ctrl+pageup", "command": "workbench.action.previousEditor" }, +{ "key": "ctrl+e", "command": "workbench.action.quickOpen" }, +{ "key": "ctrl+p", "command": "workbench.action.quickOpen" }, +{ "key": "ctrl+q", "command": "workbench.action.quickOpenView" }, +{ "key": "ctrl+shift+t", "command": "workbench.action.reopenClosedEditor" }, +{ "key": "ctrl+shift+h", "command": "workbench.action.replaceInFiles" }, +{ "key": "ctrl+shift+j", "command": "workbench.action.search.toggleQueryDetails", + "when": "searchViewletVisible" }, +{ "key": "ctrl+k ctrl+t", "command": "workbench.action.selectTheme" }, +{ "key": "ctrl+k ctrl+p", "command": "workbench.action.showAllEditors" }, +{ "key": "ctrl+t", "command": "workbench.action.showAllSymbols" }, +{ "key": "f1", "command": "workbench.action.showCommands" }, +{ "key": "ctrl+shift+p", "command": "workbench.action.showCommands" }, +{ "key": "ctrl+\\", "command": "workbench.action.splitEditor" }, +{ "key": "ctrl+k ctrl+\\", "command": "workbench.action.splitEditorOrthogonal" }, +{ "key": "ctrl+shift+b", "command": "workbench.action.tasks.build" }, +{ "key": "escape", "command": "workbench.action.terminal.clearSelection", + "when": "terminalFocus && terminalTextSelected && !terminalFindWidgetVisible" }, +{ "key": "ctrl+c", "command": "workbench.action.terminal.copySelection", + "when": "terminalFocus && terminalTextSelected" }, +{ "key": "ctrl+backspace", "command": "workbench.action.terminal.deleteWordLeft", + "when": "terminalFocus" }, +{ "key": "ctrl+delete", "command": "workbench.action.terminal.deleteWordRight", + "when": "terminalFocus" }, +{ "key": "f3", "command": "workbench.action.terminal.findNext", + "when": "terminalFindWidgetFocused" }, +{ "key": "f3", "command": "workbench.action.terminal.findNextTerminalFocus", + "when": "terminalFocus" }, +{ "key": "shift+f3", "command": "workbench.action.terminal.findPrevious", + "when": "terminalFindWidgetFocused" }, +{ "key": "shift+f3", "command": "workbench.action.terminal.findPreviousTerminalFocus", + "when": "terminalFocus" }, +{ "key": "ctrl+f", "command": "workbench.action.terminal.focusFindWidget", + "when": "terminalFindWidgetFocused" }, +{ "key": "ctrl+f", "command": "workbench.action.terminal.focusFindWidget", + "when": "terminalFocus" }, +{ "key": "alt+down", "command": "workbench.action.terminal.focusNextPane", + "when": "terminalFocus" }, +{ "key": "alt+right", "command": "workbench.action.terminal.focusNextPane", + "when": "terminalFocus" }, +{ "key": "alt+up", "command": "workbench.action.terminal.focusPreviousPane", + "when": "terminalFocus" }, +{ "key": "alt+left", "command": "workbench.action.terminal.focusPreviousPane", + "when": "terminalFocus" }, +{ "key": "shift+escape", "command": "workbench.action.terminal.hideFindWidget", + "when": "terminalFindWidgetVisible && terminalFocus" }, +{ "key": "escape", "command": "workbench.action.terminal.hideFindWidget", + "when": "terminalFindWidgetVisible && terminalFocus" }, +{ "key": "ctrl+shift+`", "command": "workbench.action.terminal.new" }, +{ "key": "ctrl+shift+c", "command": "workbench.action.terminal.openNativeConsole", + "when": "!terminalFocus" }, +{ "key": "ctrl+v", "command": "workbench.action.terminal.paste", + "when": "terminalFocus" }, +{ "key": "ctrl+alt+pagedown", "command": "workbench.action.terminal.scrollDown", + "when": "terminalFocus" }, +{ "key": "shift+pagedown", "command": "workbench.action.terminal.scrollDownPage", + "when": "terminalFocus" }, +{ "key": "ctrl+end", "command": "workbench.action.terminal.scrollToBottom", + "when": "terminalFocus" }, +{ "key": "ctrl+home", "command": "workbench.action.terminal.scrollToTop", + "when": "terminalFocus" }, +{ "key": "ctrl+alt+pageup", "command": "workbench.action.terminal.scrollUp", + "when": "terminalFocus" }, +{ "key": "shift+pageup", "command": "workbench.action.terminal.scrollUpPage", + "when": "terminalFocus" }, +{ "key": "ctrl+shift+5", "command": "workbench.action.terminal.split", + "when": "terminalFocus" }, +{ "key": "ctrl+\\", "command": "workbench.action.terminal.split", + "when": "terminalFocus" }, +{ "key": "alt+c", "command": "workbench.action.terminal.toggleFindCaseSensitive", + "when": "terminalFindWidgetFocused" }, +{ "key": "alt+c", "command": "workbench.action.terminal.toggleFindCaseSensitiveTerminalFocus", + "when": "terminalFocus" }, +{ "key": "alt+r", "command": "workbench.action.terminal.toggleFindRegex", + "when": "terminalFindWidgetFocused" }, +{ "key": "alt+r", "command": "workbench.action.terminal.toggleFindRegexTerminalFocus", + "when": "terminalFocus" }, +{ "key": "alt+w", "command": "workbench.action.terminal.toggleFindWholeWord", + "when": "terminalFindWidgetFocused" }, +{ "key": "alt+w", "command": "workbench.action.terminal.toggleFindWholeWordTerminalFocus", + "when": "terminalFocus" }, +{ "key": "ctrl+`", "command": "workbench.action.terminal.toggleTerminal" }, +{ "key": "shift+alt+0", "command": "workbench.action.toggleEditorGroupLayout" }, +{ "key": "f11", "command": "workbench.action.toggleFullScreen" }, +{ "key": "ctrl+j", "command": "workbench.action.togglePanel" }, +{ "key": "ctrl+b", "command": "workbench.action.toggleSidebarVisibility" }, +{ "key": "ctrl+k z", "command": "workbench.action.toggleZenMode" }, +{ "key": "ctrl+numpad_add", "command": "workbench.action.zoomIn" }, +{ "key": "ctrl+shift+=", "command": "workbench.action.zoomIn" }, +{ "key": "ctrl+=", "command": "workbench.action.zoomIn" }, +{ "key": "ctrl+numpad_subtract", "command": "workbench.action.zoomOut" }, +{ "key": "ctrl+shift+-", "command": "workbench.action.zoomOut" }, +{ "key": "ctrl+-", "command": "workbench.action.zoomOut" }, +{ "key": "ctrl+numpad0", "command": "workbench.action.zoomReset" }, +{ "key": "ctrl+shift+m", "command": "workbench.actions.view.problems" }, +{ "key": "ctrl+shift+y", "command": "workbench.debug.action.toggleRepl" }, +{ "key": "ctrl+k ctrl+m", "command": "workbench.extensions.action.showRecommendedKeymapExtensions" }, +{ "key": "ctrl+k c", "command": "workbench.files.action.compareWithClipboard" }, +{ "key": "ctrl+k d", "command": "workbench.files.action.compareWithSaved" }, +{ "key": "ctrl+k e", "command": "workbench.files.action.focusOpenEditorsView", + "when": "workbench.explorer.openEditorsView.active" }, +{ "key": "ctrl+shift+d", "command": "workbench.view.debug" }, +{ "key": "ctrl+shift+e", "command": "workbench.view.explorer" }, +{ "key": "ctrl+shift+x", "command": "workbench.view.extensions" }, +{ "key": "ctrl+shift+g", "command": "workbench.view.scm" }, +{ "key": "ctrl+shift+f", "command": "workbench.view.search", + "when": "!searchViewletVisible" }, +{ "key": "escape", "command": "breadcrumbs.selectEditor", + "when": "breadcrumbsActive && breadcrumbsVisible" }, +{ "key": "f11", "command": "workbench.action.debug.stepInto", + "when": "inDebugMode" }, +{ "key": "f2", "command": "debug.renameWatchExpression", + "when": "watchExpressionsFocused" }, +{ "key": "f2", "command": "debug.setVariable", + "when": "variablesFocused" }, +{ "key": "space", "command": "debug.toggleBreakpoint", + "when": "breakpointsFocused && !inputFocus" }, +{ "key": "delete", "command": "deleteFile", + "when": "explorerViewletVisible && filesExplorerFocus && !config.files.enableTrash && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "shift+delete", "command": "deleteFile", + "when": "config.files.enableTrash && explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "escape", "command": "filesExplorer.cancelCut", + "when": "explorerResourceCut && explorerViewletVisible && filesExplorerFocus && !inputFocus" }, +{ "key": "ctrl+c", "command": "filesExplorer.copy", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !inputFocus" }, +{ "key": "ctrl+x", "command": "filesExplorer.cut", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !inputFocus" }, +{ "key": "ctrl+v", "command": "filesExplorer.paste", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceReadonly && !inputFocus" }, +{ "key": "delete", "command": "moveFileToTrash", + "when": "config.files.enableTrash && explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "f2", "command": "renameFile", + "when": "explorerViewletVisible && filesExplorerFocus && !explorerResourceIsRoot && !explorerResourceReadonly && !inputFocus" }, +{ "key": "shift+escape", "command": "closeReferenceSearch", + "when": "referenceSearchVisible && !config.editor.stablePeek" }, +{ "key": "escape", "command": "closeReferenceSearch", + "when": "referenceSearchVisible && !config.editor.stablePeek" }, +{ "key": "f4", "command": "goToNextReference", + "when": "referenceSearchVisible" }, +{ "key": "shift+f4", "command": "goToPreviousReference", + "when": "referenceSearchVisible" }, +{ "key": "escape", "command": "notifications.hideList", + "when": "notificationCenterVisible" }, +{ "key": "escape", "command": "notifications.hideToasts", + "when": "notificationToastsVisible" }, +{ "key": "alt+left", "command": "workbench.action.quickInputBack", + "when": "inQuickOpen" }, +{ "key": "ctrl+tab", "command": "workbench.action.quickOpenNavigateNextInEditorPicker", + "when": "inEditorsPicker && inQuickOpen" }, +{ "key": "ctrl+e", "command": "workbench.action.quickOpenNavigateNextInFilePicker", + "when": "inFilesPicker && inQuickOpen" }, +{ "key": "ctrl+p", "command": "workbench.action.quickOpenNavigateNextInFilePicker", + "when": "inFilesPicker && inQuickOpen" }, +{ "key": "ctrl+r", "command": "workbench.action.quickOpenNavigateNextInRecentFilesPicker", + "when": "inQuickOpen && inRecentFilesPicker" }, +{ "key": "ctrl+q", "command": "workbench.action.quickOpenNavigateNextInViewPicker", + "when": "inQuickOpen && inViewsPicker" }, +{ "key": "ctrl+shift+tab", "command": "workbench.action.quickOpenNavigatePreviousInEditorPicker", + "when": "inEditorsPicker && inQuickOpen" }, +{ "key": "ctrl+shift+e", "command": "workbench.action.quickOpenNavigatePreviousInFilePicker", + "when": "inFilesPicker && inQuickOpen" }, +{ "key": "ctrl+shift+p", "command": "workbench.action.quickOpenNavigatePreviousInFilePicker", + "when": "inFilesPicker && inQuickOpen" }, +{ "key": "ctrl+shift+r", "command": "workbench.action.quickOpenNavigatePreviousInRecentFilesPicker", + "when": "inQuickOpen && inRecentFilesPicker" }, +{ "key": "ctrl+shift+q", "command": "workbench.action.quickOpenNavigatePreviousInViewPicker", + "when": "inQuickOpen && inViewsPicker" }, +{ "key": "ctrl+r", "command": "workbench.action.reloadWindow", + "when": "isDevelopment" }, +{ "key": "ctrl+shift+i", "command": "workbench.action.toggleDevTools", + "when": "isDevelopment" }, +{ "key": "ctrl+f4", "command": "extension.node-debug.pickLoadedScript", + "when": "debugType == 'node'" }, +{ "key": "ctrl+f4", "command": "extension.node-debug.pickLoadedScript", + "when": "debugType == 'node2'" }, +{ "key": "ctrl+shift+v", "command": "markdown.showPreview", + "when": "editorLangId == 'markdown'" }, +{ "key": "shift+alt+f12", "command": "references-view.find", + "when": "editorHasReferenceProvider" }, +{ "key": "f10", "command": "extension.node-debug.startWithStopOnEntry", + "when": "!inDebugMode && debugConfigurationType == 'node'" }, +{ "key": "ctrl+k v", "command": "markdown.showPreviewToSide", + "when": "editorLangId == 'markdown'" }, +{ "key": "f4", "command": "references-view.next", + "when": "reference-list.hasResult" }, +{ "key": "shift+f4", "command": "references-view.prev", + "when": "reference-list.hasResult" } +] \ No newline at end of file diff --git a/build/sitemap.xml b/build/sitemap.xml new file mode 100644 index 0000000000000000000000000000000000000000..36e170fe9073aa5e2b57ae6ec89f83789b81e479 --- /dev/null +++ b/build/sitemap.xml @@ -0,0 +1,895 @@ + + + + https://code.visualstudio.com/ + weekly + 1.00 + + + https://code.visualstudio.com/docs + weekly + 1.00 + + + https://code.visualstudio.com/updates + weekly + 0.70 + + + https://code.visualstudio.com/license + weekly + 0.70 + + + https://code.visualstudio.com/blogs + weekly + 0.70 + + + https://code.visualstudio.com/docs/supporting/FAQ + weekly + 0.70 + + + https://code.visualstudio.com/search + weekly + 0.80 + + + https://code.visualstudio.com/download + weekly + 1.0 + + + https://code.visualstudio.com/nodejs + weekly + 1.0 + + + https://code.visualstudio.com/nodejs-deployment + weekly + 1.0 + + + https://code.visualstudio.com/docs/supporting/requirements + weekly + 0.70 + + + https://code.visualstudio.com/docs/introvideos/quicktour + weekly + 0.8 + + + https://code.visualstudio.com/docs/introvideos/basics + weekly + 0.8 + + + https://code.visualstudio.com/docs/introvideos/configure + weekly + 0.8 + + + https://code.visualstudio.com/docs/introvideos/intellisense + weekly + 0.8 + + + https://code.visualstudio.com/docs/introvideos/codeediting + weekly + 0.8 + + + https://code.visualstudio.com/docs/introvideos/versioncontrol + weekly + 0.8 + + + https://code.visualstudio.com/docs/introvideos/debugging + weekly + 0.8 + + + https://code.visualstudio.com/docs/setup/setup-overview + weekly + 0.8 + + + https://code.visualstudio.com/docs/setup/mac + weekly + 0.8 + + + https://code.visualstudio.com/docs/setup/linux + weekly + 0.8 + + + https://code.visualstudio.com/docs/setup/windows + weekly + 0.8 + + + https://code.visualstudio.com/docs/setup/network + weekly + 0.8 + + + https://code.visualstudio.com/docs/setup/additional-components + weekly + 0.8 + + + https://code.visualstudio.com/docs/getstarted/introvideos + weekly + 0.8 + + + https://code.visualstudio.com/docs/getstarted/tips-and-tricks + weekly + 0.8 + + + https://code.visualstudio.com/docs/getstarted/userinterface + weekly + 0.8 + + + https://code.visualstudio.com/docs/getstarted/themes + weekly + 0.8 + + + https://code.visualstudio.com/docs/getstarted/settings + weekly + 0.8 + + + https://code.visualstudio.com/docs/getstarted/keybindings + weekly + 0.8 + + + https://code.visualstudio.com/docs/getstarted/theme-color-reference + weekly + 0.8 + + + https://code.visualstudio.com/docs/getstarted/locales + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/codebasics + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/editingevolved + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/extension-gallery + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/intellisense + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/refactoring + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/versioncontrol + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/debugging + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/command-line + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/tasks + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/integrated-terminal + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/accessibility + weekly + 0.8 + > + + https://code.visualstudio.com/docs/editor/whyvscode + weekly + 0.7 + + + https://code.visualstudio.com/docs/editor/userdefinedsnippets + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/emmet + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/multi-root-workspaces + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/variables-reference + weekly + 0.8 + + + https://code.visualstudio.com/docs/editor/portable + weekly + 0.8 + + + https://code.visualstudio.com/docs/azure/extensions + weekly + 0.8 + + + https://code.visualstudio.com/docs/azure/deployment + weekly + 0.8 + + + https://code.visualstudio.com/docs/azure/docker + weekly + 0.8 + + + https://code.visualstudio.com/docs/azure/kubernetes + weekly + 0.8 + + + https://code.visualstudio.com/docs/azure/mongodb + weekly + 0.8 + + + https://code.visualstudio.com/docs/azure/remote-debugging + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/overview + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/javascript + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/csharp + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/html + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/identifiers + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/json + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/markdown + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/powershell + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/typescript + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/css + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/php + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/python + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/go + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/tsql + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/jsconfig + weekly + 0.8 + + + https://code.visualstudio.com/docs/languages/java + weekly + 0.8 + + + https://code.visualstudio.com/docs/nodejs/working-with-javascript + weekly + 0.8 + + + https://code.visualstudio.com/docs/nodejs/nodejs-tutorial + weekly + 0.8 + + + https://code.visualstudio.com/docs/nodejs/reactjs-tutorial + weekly + 0.8 + + + https://code.visualstudio.com/docs/nodejs/vuejs-tutorial + weekly + 0.8 + + + https://code.visualstudio.com/docs/nodejs/emberjs-tutorial + weekly + 0.8 + + + https://code.visualstudio.com/docs/nodejs/angular-tutorial + weekly + 0.8 + + + https://code.visualstudio.com/docs/nodejs/node-debugging + weekly + 0.8 + + + https://code.visualstudio.com/docs/nodejs/debugging-recipes + weekly + 0.8 + + + https://code.visualstudio.com/docs/nodejs/extensions + weekly + 0.8 + + + https://code.visualstudio.com/docs/typescript/typescript-tutorial + weekly + 0.8 + + + https://code.visualstudio.com/docs/typescript/typescript-compiling + weekly + 0.8 + + + https://code.visualstudio.com/docs/typescript/typescript-debugging + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/python-tutorial + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/editing + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/linting + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/debugging + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/environments + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/tutorial-django + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/tutorial-flask + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/tutorial-deploy-app-service-on-linux + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/tutorial-deploy-containers + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/unit-testing + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/settings-reference + weekly + 0.8 + + + https://code.visualstudio.com/docs/python/jupyter-support + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/java-tutorial + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/java-webapp + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/java-testing + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/java-project + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/java-tomcat-jetty + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/java-faq + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/java-spring-boot + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/java-editing + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/java-azurefunctions + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/java-debugging + weekly + 0.8 + + + https://code.visualstudio.com/docs/java/extensions + weekly + 0.8 + + + https://code.visualstudio.com/docs/other/dotnet + weekly + 0.8 + + + https://code.visualstudio.com/docs/other/unity + weekly + 0.8 + + + https://code.visualstudio.com/docs/other/office + weekly + 0.8 + + + https://code.visualstudio.com/updates/latest + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/nodejs-deployment/getting-started + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/nodejs-deployment/create-website + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/nodejs-deployment/deploy-website + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/nodejs-deployment/express + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/nodejs-deployment/extensions + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/nodejs-deployment/publishing-changes + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/nodejs-deployment/tailing-logs + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/app-service-extension/getting-started + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/app-service-extension/create-app + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/app-service-extension/deploy-app + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/app-service-extension/tailing-logs + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/docker-extension/containerize-app + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/docker-extension/create-registry + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/docker-extension/deploy-container + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/docker-extension/getting-started + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/docker-extension/tailing-logs + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/functions-extension/getting-started + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/functions-extension/create-app + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/functions-extension/create-function + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/functions-extension/deploy-app + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/functions-extension/run-app + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/static-website/getting-started + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/static-website/create-app + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/static-website/create-storage + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/static-website/choose-deployment + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/static-website/deploy-explorer + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/static-website/deploy-cli + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/static-website/deploy-VSTS + weekly + 0.7 + + + https://code.visualstudio.com/tutorials/static-website/code-change + weekly + 0.7 + + + + + https://code.visualstudio.com/api + weekly + 0.9 + + + https://code.visualstudio.com/api/get-started/your-first-extension + weekly + 0.9 + + + https://code.visualstudio.com/api/get-started/extension-anatomy + weekly + 0.9 + + + https://code.visualstudio.com/api/get-started/wrapping-up + weekly + 0.8 + + + https://code.visualstudio.com/api/working-with-extensions/testing-extension + weekly + 0.8 + + + https://code.visualstudio.com/api/working-with-extensions/publishing-extension + weekly + 0.8 + + + https://code.visualstudio.com/api/working-with-extensions/bundling-extension + weekly + 0.8 + + + https://code.visualstudio.com/api/working-with-extensions/continuous-integration + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-capabilities/overview + weekly + 0.9 + + + https://code.visualstudio.com/api/extension-capabilities/common-capabilities + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-capabilities/theming + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-capabilities/extending-workbench + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-guides/overview + weekly + 0.9 + + + https://code.visualstudio.com/api/extension-guides/command + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-guides/color-theme + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-guides/icon-theme + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-guides/tree-view + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-guides/webview + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-guides/virtual-documents + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-guides/task-provider + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-guides/scm-provider + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-guides/debugger-extension + weekly + 0.8 + + + https://code.visualstudio.com/api/extension-guides/markdown-extension + weekly + 0.8 + + + https://code.visualstudio.com/api/language-extensions/overview + weekly + 0.9 + + + https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide + weekly + 0.8 + + + https://code.visualstudio.com/api/language-extensions/snippet-guide + weekly + 0.8 + + + https://code.visualstudio.com/api/language-extensions/language-configuration-guide + weekly + 0.8 + + + https://code.visualstudio.com/api/language-extensions/programmatic-language-features + weekly + 0.8 + + + https://code.visualstudio.com/api/language-extensions/language-server-extension-guide + weekly + 0.8 + + + https://code.visualstudio.com/api/advanced-topics/extension-host + weekly + 0.8 + + + https://code.visualstudio.com/api/advanced-topics/using-proposed-api + weekly + 0.8 + + + https://code.visualstudio.com/api/references/vscode-api + weekly + 0.9 + + + https://code.visualstudio.com/api/references/contribution-points + weekly + 0.9 + + + https://code.visualstudio.com/api/references/activation-events + weekly + 0.9 + + + https://code.visualstudio.com/api/references/extension-manifest + weekly + 0.8 + + + https://code.visualstudio.com/api/references/commands + weekly + 0.8 + + + https://code.visualstudio.com/api/references/theme-color + weekly + 0.8 + + + https://code.visualstudio.com/api/references/icons-in-labels + weekly + 0.8 + + + https://code.visualstudio.com/api/references/document-selector + weekly + 0.8 + + \ No newline at end of file diff --git a/docs/arabic-intro.md b/docs/arabic-intro.md new file mode 100644 index 0000000000000000000000000000000000000000..f9fa7504866e2ccc8f5945eef4c2a867cc134a87 --- /dev/null +++ b/docs/arabic-intro.md @@ -0,0 +1,23 @@ +# مقدمة إلى Visual Studio Code باللغة العربية + +مرحباً بك في دليل Visual Studio Code باللغة العربية. هذا الملف يهدف إلى تقديم نظرة عامة سريعة للمستخدمين الناطقين بالعربية. + +## ما هو Visual Studio Code؟ + +**Visual Studio Code** (المعروف اختصاراً بـ VS Code) هو محرر أكواد برمجية خفيف الوزن ولكنه قوي، تم تطويره بواسطة Microsoft. يعمل على أنظمة التشغيل Windows و macOS و Linux. + +### الميزات الرئيسية: +* **دعم لغات متعددة**: يدعم JavaScript و TypeScript و Node.js بشكل افتراضي، مع توفر إضافات للغات أخرى مثل Python و C++ و Java. +* **IntelliSense**: ميزة الإكمال التلقائي الذكي بناءً على أنواع المتغيرات وتعريفات الدوال. +* **تصحيح الأخطاء (Debugging)**: أدوات مدمجة لتصحيح الأخطاء مباشرة من المحرر. +* **Git المدمج**: سهولة التعامل مع مستودعات Git والأوامر الشائعة. +* **التخصيص**: يمكنك تغيير المظهر، واختصارات لوحة المفاتيح، وتثبيت الإضافات لتناسب احتياجاتك. + +## البدء السريع + +1. **التحميل**: قم بتحميل المحرر من [الموقع الرسمي](https://code.visualstudio.com/). +2. **التثبيت**: اتبع خطوات التثبيت البسيطة لنظام تشغيلك. +3. **فتح مجلد**: ابدأ مشروعك الجديد بفتح مجلد يحتوي على ملفاتك البرمجية. + +--- +*هذا الملف هو مساهمة لتعزيز المحتوى العربي في وثائق VS Code.* diff --git a/docs/azure/deployment.md b/docs/azure/deployment.md new file mode 100644 index 0000000000000000000000000000000000000000..c7c3322b690d8e00679095acbf3645bd49a02f1b --- /dev/null +++ b/docs/azure/deployment.md @@ -0,0 +1,30 @@ +--- +Order: 2 +Area: azure +TOCTitle: Deployment +PageTitle: Visual Studio Code Azure Tutorials +ContentId: 90f8dc30-1e71-4ea7-8230-2bf09bfb97d4 +MetaDescription: Visual Studio Code Azure Tutorials +DateApproved: 3/7/2019 +--- +# Deploying Applications to Azure + +Visual Studio Code makes it easy to deploy your applications to [Azure](https://azure.microsoft.com) and we've created walkthroughs to help you get started. Whether your workflow is through the [Azure CLI](https://docs.microsoft.com/cli/azure) or [Azure App Service](https://azure.microsoft.com/services/app-service), using a [Docker](https://www.docker.com) container, or creating serverless [Azure Functions](https://azure.microsoft.com/services/functions/), you'll find the deployment steps you need. + +## Deployment tutorials + +The tutorials below will walk you through creating a simple website and deploying it to Azure: + +Tutorial | Description +--- | --- +[Deploy Azure Functions](/tutorials/functions-extension/getting-started) | Build and manage Azure Functions serverless apps directly in VS Code with the Azure Functions extension. +[Deploy using the App Service extension](/tutorials/app-service-extension/getting-started) | Manage Azure resources directly in VS Code with the Azure App Service extension. +[Deploy using Docker](/tutorials/docker-extension/getting-started) | Deploy your website using a Docker container. +[Deploy using the Azure CLI](/tutorials/nodejs-deployment/getting-started) | Create, deploy, and update a website using a terminal and the Azure CLI. +[Deploy a static website](/tutorials/static-website/getting-started) | Create, deploy, and update a static website on Azure Storage. + +## Next steps + +* [Azure Extensions](/docs/azure/extensions.md) - The VS Code Marketplace has hundreds of extensions for Azure and the cloud. +* [Working with Docker](/docs/azure/docker.md) - Put your application in a Docker container for easy reuse and deployment. +* [Working with MongoDB](/docs/azure/mongodb.md) - Create, manage and query MongoDB databases from within VS Code. \ No newline at end of file diff --git a/docs/azure/docker.md b/docs/azure/docker.md new file mode 100644 index 0000000000000000000000000000000000000000..625b883128f55c8a08e7bcaefdfcb8708b60cd74 --- /dev/null +++ b/docs/azure/docker.md @@ -0,0 +1,142 @@ +--- +Order: 4 +Area: azure +TOCTitle: Docker +ContentId: 42F8B9F8-BD03-4159-9479-17C5BDE30531 +PageTitle: Working with Docker in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Working with Docker containers in Visual Studio Code. +--- +# Working with Docker + +[Docker](https://www.docker.com) is a very popular container platform that lets you easily package, deploy, and consume applications and services. Whether you are a seasoned Docker developer or just getting started, Visual Studio Code makes it easy to author `Dockerfile` and `docker-compose.yml` files in your workspace. Visual Studio Code even supports generating and [adding the appropriate Docker files](#generating-docker-files) based on your project type. + +## Install the Docker extension + +Docker support for VS Code is provided by an extension. To install the Docker extension, open the Extensions view by pressing `kb(workbench.view.extensions)` and search for `docker` to filter the results. Select the Microsoft [Docker](https://marketplace.visualstudio.com/items?itemName=PeterJausovec.vscode-docker) extension. + +![Select Docker extension](images/docker/installdockerextension.png) + +## Dockerfiles + +With Docker, you can build images by specifying the step by step commands needed to build the image in a `Dockerfile`. A Dockerfile is just a text file that contains the build instructions. + +VS Code understands the structure of Dockerfiles as well as the available set of instructions, so you get a great experience when authoring these files. + +1. Create a new file in your workspace named `Dockerfile` +2. Press `kb(editor.action.triggerSuggest)` to bring up a list of snippets corresponding to valid `Dockerfile` commands. Pressing the 'i' **Read More** button on the right will show a fly-out with details and a link to the Docker Online documentation. + + ![Dockerfile snippets](images/docker/dockerfileintellisense.png) + +3. Press `kbstyle(Tab)` to move between fields within the snippet. For example, with the `COPY` snippet you can fill in the `source` and then press `kbstyle(Tab)` to move to the `dest` field. + + ![Dockerfile snippet navigation](images/docker/dockerfiletemplate.png) + +In addition to snippets for authoring your `Dockerfile`, Visual Studio Code will provide you with a description of any Docker command you hover over with the mouse. For example, when hovering over `WORKDIR` you will see the following. + +![Dockerfile hover tooltip](images/docker/dockerfiletooltip.png) + +For more information on Dockerfiles, check out [Dockerfile best practices]( +https://docs.docker.com/articles/dockerfile_best-practices/) on [docker.com](https://docker.com). + +## Docker Compose + +[Docker Compose](https://docs.docker.com/compose/) lets you define and run multi-container applications with Docker. You define what the shape of these containers look like with a file called `docker-compose.yml`. + +Visual Studio Code's experience for authoring `docker-compose.yml` is also very rich, providing IntelliSense for valid Docker compose directives and it will query Docker Hub for metadata on public Docker images. + +1. Create a new file in your workspace called `docker-compose.yml` +2. Define a new service called `web:` +3. On the second line, bring up IntelliSense by pressing `kb(editor.action.triggerSuggest)` to see a list of all valid compose directives. + + ![Docker Compose IntelliSense](images/docker/dockercomposeintellisense.png) + +4. For the `image` directive, you can press `kb(editor.action.triggerSuggest)` again and VS Code will query the Docker Hub index for public images. + + ![Docker Compose image suggestions](images/docker/dockercomposeimageintellisense.png) + +VS Code will first show a list of popular images along with metadata such as the number of stars and description. If you continue typing VS Code will query the Docker Hub index for matching images, including searching public profiles. For example, searching for `Microsoft` will show you all the public Microsoft images. + + ![Docker Compose Microsoft image suggestions](images/docker/dockercomposesearch.png) + +## Generating Docker files + +Writing Docker and docker-compose files by hand can be tricky and time consuming. To help you, VS Code can generate the necessary Docker files for your project. From the **Command Palette** (`kb(workbench.action.showCommands)`), run the **Docker: Add Docker files to Workspace** command to generate `Dockerfile`, `docker-compose.yml`, and `docker-compose.debug.yml` files for your workspace type: + +![dockerfile](images/docker/generateFiles.gif) + +## Docker commands + +Many of the most common Docker and docker-compose commands are built right into the **Command Palette** (`kb(workbench.action.showCommands)`). + +![IntelliSense](images/docker/dockercommands.gif) + +## Docker view + +The Docker extension contributes a **Docker** view to VS Code. Within the view, the Explorer lets you view and manage your Images, Containers, and browse your Docker Hub registry. If the [Azure Account](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account) extension is installed, you can browse your [Azure Container Registries](https://docs.microsoft.com/azure/container-registry/) as well. + +The right click context menu provides quick access to the same rich set of commands found in the **Command Palette** (`kb(workbench.action.showCommands)`). + +![explorer integration](images/docker/explorer.png) + +You can move the Docker view up or down by dragging the Docker icon and you can hide the view by right clicking on the icon and choosing **Hide**. To bring it back, right click on the Activity Bar area and check the **Docker** item. + +![show and hide the view](images/docker/viewRightClick.png) + +### Logging into Docker Hub + +The first time you expand the Docker Hub node, you'll be prompted to log into your Docker Hub account. + +![Docker Hub Login](images/docker/dockerHubLogin.png) + +Your user name and password are stored in your operating system credentials vault (for example macOS keychain, Windows Credential Store) so that you don't need to log in every time. You can log out of Docker Hub by right clicking on the Docker Hub label and choosing **Docker Hub Logout**. This will delete the credentials from the OS store. + +## Configuration settings + +The Docker extension comes with a number of useful configuration [settings](/docs/getstarted/settings.md) allowing you to customize your workflow. You can control such things the default tag for an image (`docker.defaultRegistry`), the shell to use when attaching to a Docker container (`docker.attachShellCommand`), or various docker-compose settings. + +Bring up the Settings editor (`kb(workbench.action.openSettings)`) and type 'docker' in the search box to filter on the docker extension settings. + +![docker settings](images/docker/docker-settings.png) + +## Linting + +The Docker extension language service analyzes your Docker files and provides you with errors and warnings. + +![docker warnings](images/docker/linting.png) + +You can control specific linting rules to either be a warning, error, or ignored through the `docker.languageserver.diagnostics` [settings](/docs/getstarted/settings.md) + +## Deploying images to Azure App Service + +With the Docker Explorer, you can deploy images from Docker Hub or Azure Container Registries, directly to an Azure App Service instance. This functionality requires installing the [Azure Account](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account) extension and an Azure Subscription. If you do not have an Azure subscription, [sign up today](https://azure.microsoft.com/en-us/free/?b=16.48) for a free 30 day account and get $200 in Azure Credits to try out any combination of Azure services. + +To log into Azure, use the **Azure: Sign In** command from the **Command Palette** (`kb(workbench.action.showCommands)`). You will then sign into your account using the Device Login flow. Click on **Copy & Open** to open your default browser. + +![Azure Login](images/docker/devicelogin.png) + +Paste in the access code and continue the sign in process. + +![Azure Login](images/docker/devicelogin2.png) + +You can now right click on an image in Docker Hub or an Azure Container Registry and choose **Deploy Image to Azure App Service**. + +![Deploy to Azure](images/docker/deploytoazure.png) + +From here, you will be prompted for an Azure Resource Group, a location, an App Service Plan, and a globally unique website name. + +To see the full workflow, there is a detailed [Deploy using Docker](/tutorials/docker-extension/getting-started.md) tutorial that creates a web application, puts it into a Docker container, pushes it to an Azure Container Registry, and then deploys to Azure. + +## Connecting to `docker-machine` + +The default connection of the extension is to connect to the local docker daemon. You can connect to a docker-machine instance if you launch VS Code and have the `DOCKER_HOST` environment variable set to a valid host. + +## Running commands on Linux + +By default, Docker runs as the root user on Linux, requiring other users to access it with `sudo`. This extension does not assume root access, so you will need to create a Unix group called "docker" and add users to it. Instructions can be found here: [Create a Docker group](https://docs.docker.com/install/linux/linux-postinstall/). + +## Next steps + +* [Azure Extensions](/docs/azure/extensions.md) - The VS Code Marketplace has hundreds of extensions for Azure and the cloud. +* [Deploying to Azure](/docs/azure/deployment.md) - Learn step-by-step how to deploy your application to Azure. +* [Working with MongoDB](/docs/azure/mongodb.md) - Create, manage and query MongoDB databases from within VS Code. diff --git a/docs/azure/extensions.md b/docs/azure/extensions.md new file mode 100644 index 0000000000000000000000000000000000000000..402a37fcfc2bb540cccdfa0b953e8b42580ca488 --- /dev/null +++ b/docs/azure/extensions.md @@ -0,0 +1,35 @@ +--- +Order: 1 +Area: azure +TOCTitle: Extensions +PageTitle: Visual Studio Code Azure Extensions +ContentId: d2e93075-4cfe-48f4-b05e-f985c86d9713 +MetaDescription: Visual Studio Code Azure Extensions +DateApproved: 3/7/2019 +--- +# Azure Extensions + +You can use [Azure](https://azure.microsoft.com) directly from Visual Studio Code through extensions. Using either the [Azure CLI](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azurecli) or the [Azure App Service](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) extension, you can have your application running in Azure in minutes. + +![app service](images/extensions/azure-app-service-tools.png) + +## Visual Studio Code Marketplace + +There are many VS Code extensions on the [Marketplace](https://marketplace.visualstudio.com/search?term=azure&target=VSCode&category=All%20categories&sortBy=Relevance) that make it easy to build and host applications on Azure. + +
+ +> **Tip:** Click on an extension tile above to read the description and reviews in the Marketplace. + +There is also a [Node Pack for Azure](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack) extension pack which bundles useful Azure extensions for Node.js developers into a single installation. + +## Searching for extensions + +You can also search for Azure or cloud extensions in the VS Code Extensions view (`kb(workbench.view.extensions)`) and typing 'azure' and sorting by popularity (Sort By: Install Count) and ratings (Sort By: Rating). + +![popular Azure extensions](images/extensions/popular-azure-extensions.png) + +## Next steps + +* [Deploying to Azure](/docs/azure/deployment.md) - Learn step-by-step how to deploy your application to Azure. +* [Working with Docker](/docs/azure/docker.md) - Put your application in a Docker container for easy reuse and deployment. diff --git a/docs/azure/images/docker/deploytoazure.png b/docs/azure/images/docker/deploytoazure.png new file mode 100644 index 0000000000000000000000000000000000000000..2cce9cfd9ee035b8d64292b3046bdc6c0f21c5f8 Binary files /dev/null and b/docs/azure/images/docker/deploytoazure.png differ diff --git a/docs/azure/images/docker/devicelogin.png b/docs/azure/images/docker/devicelogin.png new file mode 100644 index 0000000000000000000000000000000000000000..5194a3c7a99b354b7671b8dc14095627129a17fb Binary files /dev/null and b/docs/azure/images/docker/devicelogin.png differ diff --git a/docs/azure/images/docker/devicelogin2.png b/docs/azure/images/docker/devicelogin2.png new file mode 100644 index 0000000000000000000000000000000000000000..ba80b893326f1e4240ef4edd1786216a05868fd1 Binary files /dev/null and b/docs/azure/images/docker/devicelogin2.png differ diff --git a/docs/azure/images/docker/docker-settings.png b/docs/azure/images/docker/docker-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..9720bebfc12de9d043535ab9cbbad392e5e2242b Binary files /dev/null and b/docs/azure/images/docker/docker-settings.png differ diff --git a/docs/azure/images/docker/dockerHubLogin.png b/docs/azure/images/docker/dockerHubLogin.png new file mode 100644 index 0000000000000000000000000000000000000000..47bd0c846e9369f6293a2d51457674fe2ec5de98 Binary files /dev/null and b/docs/azure/images/docker/dockerHubLogin.png differ diff --git a/docs/azure/images/docker/dockercommands.gif b/docs/azure/images/docker/dockercommands.gif new file mode 100644 index 0000000000000000000000000000000000000000..752edc831274f51bde11ba03d55eedd965b9b598 --- /dev/null +++ b/docs/azure/images/docker/dockercommands.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:42d873870b2a9ce88dc0c818690e1ac9f2521d50abbeaa5a7ee041d75f83c33d +size 181681 diff --git a/docs/azure/images/docker/dockercomposeimageintellisense.png b/docs/azure/images/docker/dockercomposeimageintellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..6f0c90f6e15fca8bdc4d47cade10f79168c8aec8 Binary files /dev/null and b/docs/azure/images/docker/dockercomposeimageintellisense.png differ diff --git a/docs/azure/images/docker/dockercomposeintellisense.png b/docs/azure/images/docker/dockercomposeintellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..56328d1a8fb6084431dfac384c01269897dff93f Binary files /dev/null and b/docs/azure/images/docker/dockercomposeintellisense.png differ diff --git a/docs/azure/images/docker/dockercomposesearch.png b/docs/azure/images/docker/dockercomposesearch.png new file mode 100644 index 0000000000000000000000000000000000000000..7ad74a475f029426a388f826fee1f2cae0294536 Binary files /dev/null and b/docs/azure/images/docker/dockercomposesearch.png differ diff --git a/docs/azure/images/docker/dockerfileintellisense.png b/docs/azure/images/docker/dockerfileintellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..8d5d326e92ca6c3e8399fc9429c6e8ed3f39f6db Binary files /dev/null and b/docs/azure/images/docker/dockerfileintellisense.png differ diff --git a/docs/azure/images/docker/dockerfiletemplate.png b/docs/azure/images/docker/dockerfiletemplate.png new file mode 100644 index 0000000000000000000000000000000000000000..de80f0c3f975538f3b089c7fe87288c27be98265 Binary files /dev/null and b/docs/azure/images/docker/dockerfiletemplate.png differ diff --git a/docs/azure/images/docker/dockerfiletooltip.png b/docs/azure/images/docker/dockerfiletooltip.png new file mode 100644 index 0000000000000000000000000000000000000000..e787f2048e4aee2dc2bc9e22ddf1e8afac244de9 Binary files /dev/null and b/docs/azure/images/docker/dockerfiletooltip.png differ diff --git a/docs/azure/images/docker/explorer.png b/docs/azure/images/docker/explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..a02468089370611ab24d69e6c7e9667c12a0d59e Binary files /dev/null and b/docs/azure/images/docker/explorer.png differ diff --git a/docs/azure/images/docker/generateFiles.gif b/docs/azure/images/docker/generateFiles.gif new file mode 100644 index 0000000000000000000000000000000000000000..48f4253c4b520d8f4fb735be8f50284029518a72 --- /dev/null +++ b/docs/azure/images/docker/generateFiles.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:21a5e4c79e2e2b45b102a96bc1ccf4a18918dd9b7f307a97c603c4824b955045 +size 258789 diff --git a/docs/azure/images/docker/installdockerextension.png b/docs/azure/images/docker/installdockerextension.png new file mode 100644 index 0000000000000000000000000000000000000000..ef7ef5b67ae6e7a860c2560270702ee28184c54f Binary files /dev/null and b/docs/azure/images/docker/installdockerextension.png differ diff --git a/docs/azure/images/docker/linting.png b/docs/azure/images/docker/linting.png new file mode 100644 index 0000000000000000000000000000000000000000..c99af90fb5d1136467e4442c2f67ea9b49e5183e Binary files /dev/null and b/docs/azure/images/docker/linting.png differ diff --git a/docs/azure/images/docker/viewRightClick.png b/docs/azure/images/docker/viewRightClick.png new file mode 100644 index 0000000000000000000000000000000000000000..4aaef7484b9fd5d8200f61f92367dde208fdac26 Binary files /dev/null and b/docs/azure/images/docker/viewRightClick.png differ diff --git a/docs/azure/images/extensions/azure-app-service-tools.png b/docs/azure/images/extensions/azure-app-service-tools.png new file mode 100644 index 0000000000000000000000000000000000000000..9fba38f34b2154e498087f32c8312f3a9139708e Binary files /dev/null and b/docs/azure/images/extensions/azure-app-service-tools.png differ diff --git a/docs/azure/images/extensions/popular-azure-extensions.png b/docs/azure/images/extensions/popular-azure-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..f7734f5834200c9846869a197f244e99c069e7cf Binary files /dev/null and b/docs/azure/images/extensions/popular-azure-extensions.png differ diff --git a/docs/azure/images/kubernetes/check-status.gif b/docs/azure/images/kubernetes/check-status.gif new file mode 100644 index 0000000000000000000000000000000000000000..14813309eed73718770a4c2e8ec5cb3db9283d78 --- /dev/null +++ b/docs/azure/images/kubernetes/check-status.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b633d89ddff8fa35250341b3188a941824d516d83dab0814c841be01cb8315ba +size 811050 diff --git a/docs/azure/images/kubernetes/create-k8s.gif b/docs/azure/images/kubernetes/create-k8s.gif new file mode 100644 index 0000000000000000000000000000000000000000..25510274d1a5cc4d2eeeb783f0a2ed394491c37f --- /dev/null +++ b/docs/azure/images/kubernetes/create-k8s.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6b7c3acc0c0e87b5e86b5aef9e42f4c56da917e7d979f11a58390d165d684611 +size 655600 diff --git a/docs/azure/images/kubernetes/create-manifest.gif b/docs/azure/images/kubernetes/create-manifest.gif new file mode 100644 index 0000000000000000000000000000000000000000..dcd2772826c4cca9495f402ef425e641d9e3a255 --- /dev/null +++ b/docs/azure/images/kubernetes/create-manifest.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:62ad8b35862285d95626732c746e1f2f4cc439647756c9ea954032bb2c25372f +size 520205 diff --git a/docs/azure/images/kubernetes/error-creating-clusters-RSA.png b/docs/azure/images/kubernetes/error-creating-clusters-RSA.png new file mode 100644 index 0000000000000000000000000000000000000000..bf911012c3f3cb7c45959096b19a587a87be041f Binary files /dev/null and b/docs/azure/images/kubernetes/error-creating-clusters-RSA.png differ diff --git a/docs/azure/images/kubernetes/error-creating-clusters.png b/docs/azure/images/kubernetes/error-creating-clusters.png new file mode 100644 index 0000000000000000000000000000000000000000..b25bf58294d9d4196c2ee5e4cc2a705e51c11beb Binary files /dev/null and b/docs/azure/images/kubernetes/error-creating-clusters.png differ diff --git a/docs/azure/images/kubernetes/install-kubernetes.png b/docs/azure/images/kubernetes/install-kubernetes.png new file mode 100644 index 0000000000000000000000000000000000000000..01ee661606135f09248bcb6d9f0b709110f92f54 --- /dev/null +++ b/docs/azure/images/kubernetes/install-kubernetes.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7b12ee7b74dc9a677a9148c3501623327bcbd0cafcb203977efd690b9f3da87f +size 135401 diff --git a/docs/azure/images/kubernetes/manifest-example.png b/docs/azure/images/kubernetes/manifest-example.png new file mode 100644 index 0000000000000000000000000000000000000000..6d4191cbe806409f13c72585ab9293fb425628a0 Binary files /dev/null and b/docs/azure/images/kubernetes/manifest-example.png differ diff --git a/docs/azure/images/kubernetes/start-deployment.gif b/docs/azure/images/kubernetes/start-deployment.gif new file mode 100644 index 0000000000000000000000000000000000000000..2ca46a988e7f476f61f3b2ec0f84b214e22f6f34 --- /dev/null +++ b/docs/azure/images/kubernetes/start-deployment.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2dc6f510f07de6cd80a21d3d72d98ce08870e31da6774508a5efca9eb3a791ec +size 420327 diff --git a/docs/azure/images/mongodb/attach-database-account.png b/docs/azure/images/mongodb/attach-database-account.png new file mode 100644 index 0000000000000000000000000000000000000000..0f36686f32d3e4c67db0187e54f07c440c71dc50 Binary files /dev/null and b/docs/azure/images/mongodb/attach-database-account.png differ diff --git a/docs/azure/images/mongodb/attached-mongodb-database.png b/docs/azure/images/mongodb/attached-mongodb-database.png new file mode 100644 index 0000000000000000000000000000000000000000..a1086c11ace35190bea51c651b8b01ae47146c10 Binary files /dev/null and b/docs/azure/images/mongodb/attached-mongodb-database.png differ diff --git a/docs/azure/images/mongodb/cosmosdb-context-menu.png b/docs/azure/images/mongodb/cosmosdb-context-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..5f1051a746b7f9ca14d38982d04d3a44923afb8d Binary files /dev/null and b/docs/azure/images/mongodb/cosmosdb-context-menu.png differ diff --git a/docs/azure/images/mongodb/cosmosdb-explorer.png b/docs/azure/images/mongodb/cosmosdb-explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..1ca554129341b362a27bcb244fc5f672a6527e8d Binary files /dev/null and b/docs/azure/images/mongodb/cosmosdb-explorer.png differ diff --git a/docs/azure/images/mongodb/create-cosmosdb-account.png b/docs/azure/images/mongodb/create-cosmosdb-account.png new file mode 100644 index 0000000000000000000000000000000000000000..a5af1530a7cff1d7325c7f10b582aca1546c14b2 Binary files /dev/null and b/docs/azure/images/mongodb/create-cosmosdb-account.png differ diff --git a/docs/azure/images/mongodb/devicelogin.png b/docs/azure/images/mongodb/devicelogin.png new file mode 100644 index 0000000000000000000000000000000000000000..5194a3c7a99b354b7671b8dc14095627129a17fb Binary files /dev/null and b/docs/azure/images/mongodb/devicelogin.png differ diff --git a/docs/azure/images/mongodb/devicelogin2.png b/docs/azure/images/mongodb/devicelogin2.png new file mode 100644 index 0000000000000000000000000000000000000000..ba80b893326f1e4240ef4edd1786216a05868fd1 Binary files /dev/null and b/docs/azure/images/mongodb/devicelogin2.png differ diff --git a/docs/azure/images/mongodb/install-cosmosdb-extension.png b/docs/azure/images/mongodb/install-cosmosdb-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..2c2dd82df67a5466cf3fbd147c82ebed32523638 Binary files /dev/null and b/docs/azure/images/mongodb/install-cosmosdb-extension.png differ diff --git a/docs/azure/images/mongodb/mongodb-commands.png b/docs/azure/images/mongodb/mongodb-commands.png new file mode 100644 index 0000000000000000000000000000000000000000..602f01c359ed49cc9a7a2342c7756ec9dfce02ff Binary files /dev/null and b/docs/azure/images/mongodb/mongodb-commands.png differ diff --git a/docs/azure/images/mongodb/new-mongo-scrapbook.png b/docs/azure/images/mongodb/new-mongo-scrapbook.png new file mode 100644 index 0000000000000000000000000000000000000000..6898beed8fc16161f07cd8d7b56371193abd2f11 Binary files /dev/null and b/docs/azure/images/mongodb/new-mongo-scrapbook.png differ diff --git a/docs/azure/images/mongodb/open-document.png b/docs/azure/images/mongodb/open-document.png new file mode 100644 index 0000000000000000000000000000000000000000..5e72f8c685f100baeb2fda8f707fb1e2fe46f3e2 Binary files /dev/null and b/docs/azure/images/mongodb/open-document.png differ diff --git a/docs/azure/images/mongodb/scrapbook.png b/docs/azure/images/mongodb/scrapbook.png new file mode 100644 index 0000000000000000000000000000000000000000..feb8eca83188740c04dbb343e001d97bb1a5e229 Binary files /dev/null and b/docs/azure/images/mongodb/scrapbook.png differ diff --git a/docs/azure/images/remote-debugging/app-service-explorer.png b/docs/azure/images/remote-debugging/app-service-explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..33f43a7e015095b1f786053decf1108186f8e7a2 Binary files /dev/null and b/docs/azure/images/remote-debugging/app-service-explorer.png differ diff --git a/docs/azure/images/remote-debugging/install-app-service.png b/docs/azure/images/remote-debugging/install-app-service.png new file mode 100644 index 0000000000000000000000000000000000000000..39010778a1fe02e267db0c2a51d68aa3b224fd05 Binary files /dev/null and b/docs/azure/images/remote-debugging/install-app-service.png differ diff --git a/docs/azure/images/remote-debugging/remote-breakpoint.png b/docs/azure/images/remote-debugging/remote-breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..64d95e2ffc0a254f246b8597a28e1da05b661c1e --- /dev/null +++ b/docs/azure/images/remote-debugging/remote-breakpoint.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:74e9f1586f204fe5474fbcf980e43abcf971d874c75c92dd95d25224a7bdd24e +size 238838 diff --git a/docs/azure/images/remote-debugging/start-remote-debugging.png b/docs/azure/images/remote-debugging/start-remote-debugging.png new file mode 100644 index 0000000000000000000000000000000000000000..0fa8fec5cdbc60709ccc3322d65f5f0b04c26737 --- /dev/null +++ b/docs/azure/images/remote-debugging/start-remote-debugging.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0077bbfaf46285bb00c35244b1a354a4c4d1b4cf2868b944a4102e1b7e6bf541 +size 113538 diff --git a/docs/azure/kubernetes.md b/docs/azure/kubernetes.md new file mode 100644 index 0000000000000000000000000000000000000000..c6c71eb56ef7084dc933aa85e0c6c760ddebb667 --- /dev/null +++ b/docs/azure/kubernetes.md @@ -0,0 +1,77 @@ +--- +Order: 6 +Area: azure +TOCTitle: Kubernetes +ContentId: d0ece2e4-8dd2-4c0d-a773-604542651c9e +PageTitle: Working with Kubernetes in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Working with Kubernetes in Visual Studio Code +--- +# Working with Kubernetes in VS Code + +This document will walk you through the process of deploying an application to [Kubernetes](https://kubernetes.io/) with Visual Studio Code. [Kubernetes](https://kubernetes.io/) is an open-source system for automating deployment, scaling, and management of containerized applications. We will show you how to create a Kubernetes cluster, write a Kubernetes manifest file (usually written in YAML), which tells Kubernetes everything it needs to know about the application, and then finally deploy the application to the Kubernetes cluster. + +## Before you begin + +You will need to have tools for [Docker](https://docker.com/) and [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/). See the [Install Docker](https://docs.docker.com/install/) documentation for details on setting up Docker on your machine and [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). Before proceeding further, verify you can run Docker and kubectl commands from the shell. + +You can create a local Kubernetes cluster with [minikube](https://kubernetes.io/docs/getting-started-guides/minikube/) or an Azure Kubernetes cluster in [Azure Kubernetes Service (AKS)](https://docs.microsoft.com/azure/aks/). In this tutorial, we will use [Azure Kubernetes Service (AKS)](https://docs.microsoft.com/azure/aks/) and you will need to have your [Azure](https://www.azure.com) account ready for the deployment steps. + +In addition, if you want to iteratively run and debug containers directly in Azure Kubernetes Service (AKS), you can install the +[Azure Dev Spaces](https://marketplace.visualstudio.com/items?itemName=azuredevspaces.azds) extension. There's also an additional [Java Debugger for Azure Dev Spaces](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debugger-azds) extension, which helps boost remote debugging performance for Java application running in [Azure Dev Spaces](https://docs.microsoft.com/en-us/azure/dev-spaces/). + +## Install the Kubernetes extension + +For a fully integrated Kubernetes experience, you can install the [Kubernetes Tools](https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.vscode-kubernetes-tools) extension, which lets you quickly develop Kubernetes manifests and HELM charts. With the extension, you can also deploy containerized micro-service based applications to local or Azure Kubernetes clusters and debug your live applications running in containers on Kubernetes clusters. It also makes it easy to browse and manage your Kubernetes clusters in VS Code and provides seamless integration with [Draft](https://draft.sh/) to streamline Kubernetes development. + +To install the Kubernetes extension, open the Extensions view (`kb(workbench.view.extensions)`) and search for "kubernetes". Select the Microsoft [Kubernetes](https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.vscode-kubernetes-tools) extension. + +![Install Kubernetes](images/kubernetes/install-kubernetes.png) + +## Containerize and publish the application + +You can follow the [Working with Docker](/docs/azure/docker.md) tutorial to build your project, generate a Docker image, and push it to a public or private container registry through the Microsoft [Docker Extension](https://marketplace.visualstudio.com/items?itemName=PeterJausovec.vscode-docker). + +## Create and config a Kubernetes cluster + +You can create a Kubernetes cluster running on Azure using the Kubernetes extension in VS Code. Once you have installed the Kubernetes extension, you will see **KUBERNETES** in the Explorer. Click on **More** and choose **Create Cluster**. Follow the instructions to choose the cluster type (here we choose **Azure Kubernetes Service**), select your subscription, and set up the Azure cluster and Azure agent settings. It will take a few minutes to complete the whole workflow. + +![Create Kubernetes](images/kubernetes/create-k8s.gif) + +**Important**: To create a Kubernetes cluster on Azure, you need to install the [Azure CLI](https://docs.microsoft.com/cli/azure/get-started-with-azure-cli?view=azure-cli-latest) and sign in. + +**Tip**: You will encounter an error if you don't have an available RSA key file. Follow [create SSH public-private key](https://docs.microsoft.com/azure/virtual-machines/linux/mac-create-ssh-keys) to create your key before creating an Azure Kubernetes cluster. + +![Error with RSA](images/kubernetes/error-creating-clusters-RSA.png) + +**Tip**: You might encounter an error indicating conflicting location and VM size when creating an Azure Kubernetes cluster. Pay attention to choose proper location and VM size. + +![Error creating cluster](images/kubernetes/error-creating-clusters.png) + +## Deploy the application to Azure Kubernetes Service + +The Kubernetes extension provides autocompletion, code snippets, and verification for the Kubernetes manifest file. For example, once you type 'Deployment', a manifest file with fundamental structure is autogenerated for you. You only need to enter your app name, image, and port manually. + +![Create manifest](images/kubernetes/create-manifest.gif) + +Below is an example manifest file: + +![Manifest example](images/kubernetes/manifest-example.png) + +Once your manifest file is ready, you only need one command to start a deployment. Open the **Command Palette** (`kb(workbench.action.showCommands)`) and run **Kubernetes: Create**. It will deploy the application to your Kubernetes cluster and create objects according to the configuration in the open Kubernetes manifest file. + +![Start deployment](images/kubernetes/start-deployment.gif) + +### Checking on your deployment + +After deployment, the Kubernetes extension can help you check the status of your application. From the Explorer, click on **Workloads**, right click on **Pods** and then choose **Get** to see whether the application has started. To view the status of your app, select **Services**, right click on your app, and then click **Get**. The status will be printed to the Integrated Terminal. Once your application has an `EXTERNAL_IP`, you can open a browser and see your web app running. + +![Check status](images/kubernetes/check-status.gif) + +Congratulations! Now your app is successfully running in Azure Kubernetes Service! + +## Next steps + +* [Azure Dev Spaces](https://docs.microsoft.com/azure/dev-spaces) - Learn more about Azure Dev Spaces, a rapid, iterative Kubernetes development experience for teams. +* [Azure Extensions](/docs/azure/extensions.md) - The VS Code Marketplace has hundreds of extensions for Azure and the cloud. +* [Deploying to Azure](/docs/azure/deployment.md) - Learn step-by-step how to deploy your application to Azure. diff --git a/docs/azure/mongodb.md b/docs/azure/mongodb.md new file mode 100644 index 0000000000000000000000000000000000000000..479b4ab6124b9bef60b21b196ce505d027986289 --- /dev/null +++ b/docs/azure/mongodb.md @@ -0,0 +1,94 @@ +--- +Order: 5 +Area: azure +TOCTitle: MongoDB +PageTitle: Working with MongoDB in Visual Studio Code +ContentId: d1187f99-354f-4798-9c19-e432e4ae8572 +MetaDescription: Working with MongoDB in Visual Studio Code +DateApproved: 3/7/2019 +--- +# Working with MongoDB + +Visual Studio Code has great support for working with [MongoDB](https://www.mongodb.com/what-is-mongodb) databases. Through the [Azure CosmosDB](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb) extension, you can create, manage and query MongoDB databases from within VS Code. + +## Install the extension + +MongoDB support for VS Code is provided by the [Azure Cosmos DB](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb) extension. To install the Cosmos DB extension, open the Extensions view by pressing `kb(workbench.view.extensions)` and search for 'cosmos' to filter the results. Select the Microsoft **Azure Cosmos DB** extension. + +![Select Cosmos DB extension](images/mongodb/install-cosmosdb-extension.png) + +## Connect to MongoDB + +Once you've installed the Cosmos DB extension and reloaded VS Code, you'll notice there is a new **Azure** Activity Bar view. Click on the Azure view and you'll see the Cosmos DB Explorer. + +![cosmos db explorer](images/mongodb/cosmosdb-explorer.png) + +To connect to a MongoDB database, expand the **Attached Database Accounts** and click **Attach Database Account**, and choose the **MongoDB** from the Database Account API drop-down list. + +![attach database account drop-down](images/mongodb/attach-database-account.png) + +Enter a connection string to the database, the default is your local MongoDB server at `mongodb://127.0.0.1:27017`. You can enter any connection string, to local or remote MongoDB servers. + +>**Note**: Make sure your MongoDB server (mongod.exe) is running if you are connecting to a local MongoDB server. + +Once attached, you can work with the MongoDB server, managing MongoDB Databases, Collections and Documents. + +![attached MongoDB database](images/mongodb/attached-mongodb-database.png) + +You can **Open Collection** to see the raw JSON Collection or click on individual MongoDB Documents to see just their JSON. + +![open mongodb document](images/mongodb/open-document.png) + +Changes to the Document JSON in the editor will update the Document stored in the Collection. You will see a notification to **Upload** the entity update. To silence the notification, you can choose to **Always upload**, which modifies the `cosmosDB.showSavePrompt` [setting](/docs/getstarted/settings.md) value to false. + +## MongoDB Commands + +There are MongoDB specific commands available in the VS Code **Command Palette** (`kb(workbench.action.showCommands)`) as well as through Explorer context menus. + +![mongodb commands](images/mongodb/mongodb-commands.png) + +## Using Scrapbooks + +One of the most powerful features of the VS Code MongoDB integration is **Mongo Scrapbooks**. Scrapbooks let you create, run, and save MongoDB commands from a VS Code editor. Create a new scrapbook from the Cosmos DB Explorer or with the **Cosmos DB: New Mongo Scrapbook** command. + +![new mongo scrapbook](images/mongodb/new-mongo-scrapbook.png) + +In a scrapbook, you can reference MongoDB entities and commands and you get rich IntelliSense as you type. At the top of the editor and above each line, you will find commands to manage connections and execute your commands. Scrapbooks are extremely useful for saving database operations and queries for later reuse. + +![mongodb scrapbook](images/mongodb/scrapbook.png) + +## MongoDB on Azure + +You can easily host your MongoDB databases in the cloud on Azure with [Cosmos DB](https://docs.microsoft.com/azure/cosmos-db/introduction). + +### Azure sign in + +The Cosmos DB extension includes the [Azure Account](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account) extension which allows you to sign into Azure. If you don't have an Azure Subscription, you can [sign up today](https://azure.microsoft.com/en-us/free/?b=16.48) for a free 30 day account and get $200 in Azure Credits to try out any combination of Azure services. + +To log into Azure, use the **Sign in to Azure** command in the Cosmos DB Explorer or **Azure: Sign In** from the **Command Palette** (`kb(workbench.action.showCommands)`). You will then sign into your account using the Device Login flow. Click on **Copy & Open** to open your default browser. + +![Azure Login](images/mongodb/devicelogin.png) + +Paste in the access code and continue the sign in process. + +![Azure Login](images/mongodb/devicelogin2.png) + +In VS Code, you can sign out of Azure with **Azure: Sign Out** command. + +### Create a Cosmos DB account + +To create Cosmos DB assets on Azure, you need a Cosmos DB account. Create a Cosmos DB account with the **Create Account** '+' icon on the Explorer toolbar or with the **Cosmos DB: Create Account** command in the **Command Palette** (`kb(workbench.action.showCommands)`). + +![create CosmosDB account](images/mongodb/create-cosmosdb-account.png) + +Follow the prompts to select an Azure Subscription, enter a Cosmos DB account name, choose the API to use (MongoDB), create or reuse an Azure Resource Group, and pick a geographical location. Once the Cosmos DB account is created (it may take several minutes), you will see the Cosmos DB asset in the Explorer. Right click to see the context menu where you can start creating MongoDB databases, open the Azure portal, or copy the connection string for later to use as an environment variable with your application. + +![Cosmos DB content menu](images/mongodb/cosmosdb-context-menu.png) + +To learn more about MongoDB databases on Azure, see [Introduction to Azure Cosmos DB: MongoDB API](https://docs.microsoft.com/azure/cosmos-db/mongodb-introduction). Azure Cosmos DB also lets you host other database types such as SQL, Graph (Gremlin), Apache Cassandra through it's full set of [database APIs](https://docs.microsoft.com/azure/cosmos-db/). + +## Next steps + +* [Azure Extensions](/docs/azure/extensions.md) - The VS Code Marketplace has hundreds of extensions for Azure and the cloud. +* [Deploying to Azure](/docs/azure/deployment.md) - Learn step-by-step how to deploy your application to Azure. +* [Working with Docker](/docs/azure/docker.md) - Put your application in a Docker container for easy reuse and deployment. diff --git a/docs/azure/remote-debugging.md b/docs/azure/remote-debugging.md new file mode 100644 index 0000000000000000000000000000000000000000..b15be66721f857ef51a2644e65857eb7e1b829f5 --- /dev/null +++ b/docs/azure/remote-debugging.md @@ -0,0 +1,46 @@ +--- +Order: 3 +Area: azure +TOCTitle: Remote Debugging for Node.js +PageTitle: Azure Remote Debugging for Node.js with Visual Studio Code +ContentId: 09cb23b6-b1e9-4a29-a934-cbc16fe109c7 +MetaDescription: Azure Remote Debugging for Node.js with Visual Studio Code +DateApproved: +--- +# Azure Remote Debugging for Node.js + +Connect the Visual Studio Code debugger to your Node.js applications running on **Azure App Service** on **Linux**. The debugger works the same as when it's connected to a local Node.js process - including the use of Breakpoints and Logpoints. + +## Install the extension + +Remote debugging support for VS Code is provided by the [Azure App Service](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) extension for apps deployed to Azure. To install the Azure App Service extension, open the Extensions view by pressing `kb(workbench.view.extensions)` and search for 'app service' to filter the results. Select the Microsoft **Azure App Service** extension. + +![Select App Service extension](images/remote-debugging/install-app-service.png) + +## Connect to Azure + +Once you've installed the Azure App Service extension, you'll notice there is a new **Azure** Activity Bar view. Click on the Azure view and you'll see the Azure App Service Explorer. + +![App Service explorer](images/remote-debugging/app-service-explorer.png) + +Click **Sign in to Azure** in the App Service Explorer or **Azure: Sign In** from the **Command Palette** (`kb(workbench.action.showCommands)`) to sign in to your Azure Account. If you don't have an account, click **Create a Free Azure Account...** to create a free account and get $200 in Azure Credits to try out any combination of Azure services. + +> **Tip:** If you don't have an app deployed to Azure App Service, start by following [this tutorial](https://code.visualstudio.com/tutorials/app-service-extension/getting-started) to get an app deployed. + +## Start a remote debugging session + +Right-click your app in the App Service explorer and select **Start Remote Debugging**. This process requires that the app be restarted with the debugger enabled - you'll be prompted to confirm the restart. + +![Start remote debugging](images/remote-debugging/start-remote-debugging.png) + +Once restarted, VS Code will connect to the app's debugging port via an SSH tunnel. It may take a little time to establish the connection. Once connected, VS Code will switch into debugging mode and work the same as it does when debugging an app locally. + +![Remote breakpoint](images/remote-debugging/remote-breakpoint.png) + +When you're ready to end your remote debugging session, disconnect from the debugger as you would normally and confirm that you want to restart the app. + +## Next steps + +* [Logpoints](/docs/editor/debugging.md#logpoints) - Use Logpoints to log to the console without "breaking" in the debugger. +* [Azure Extensions](/docs/azure/extensions.md) - The VS Code Marketplace has hundreds of extensions for Azure and the cloud. +* [Deploying to Azure](/docs/azure/deployment.md) - Learn step-by-step how to deploy your application to Azure. diff --git a/docs/azure/tryappservice.md b/docs/azure/tryappservice.md new file mode 100644 index 0000000000000000000000000000000000000000..8b2f48799d20a7d38631e3a57f8865b05b4a0c2b --- /dev/null +++ b/docs/azure/tryappservice.md @@ -0,0 +1,14 @@ +--- +Order: 7 +Area: azure +TOCTitle: Try Azure App Service +ContentId: d99d21e4-f799-48ba-a7bc-58953d71c39d +PageTitle: Try Azure App Service +DateApproved: 3/7/2019 +MetaDescription: Try Azure App Service for a limited time without a subscription, free of charge and commitment. +--- +# Try Azure App Service + +Quickly and easily build web and mobile apps for any platform or device with Azure App Service. + +Try Azure App Service for a limited time without a subscription, free of charge and commitment. \ No newline at end of file diff --git a/docs/customization/keyboard-shortcuts-linux.docx b/docs/customization/keyboard-shortcuts-linux.docx new file mode 100644 index 0000000000000000000000000000000000000000..1428c492924ec40d75a64672a81743cf268d9db0 Binary files /dev/null and b/docs/customization/keyboard-shortcuts-linux.docx differ diff --git a/docs/customization/keyboard-shortcuts-macos.docx b/docs/customization/keyboard-shortcuts-macos.docx new file mode 100644 index 0000000000000000000000000000000000000000..51795e7c7cbfe29f8b1cf6b18994f23f0c2255c7 Binary files /dev/null and b/docs/customization/keyboard-shortcuts-macos.docx differ diff --git a/docs/customization/keyboard-shortcuts-windows.docx b/docs/customization/keyboard-shortcuts-windows.docx new file mode 100644 index 0000000000000000000000000000000000000000..dd114cb9366b6015c6f3b02a4eb5eff23d6585c2 Binary files /dev/null and b/docs/customization/keyboard-shortcuts-windows.docx differ diff --git a/docs/customization/keyboard-shortcuts.md b/docs/customization/keyboard-shortcuts.md new file mode 100644 index 0000000000000000000000000000000000000000..65ea8bbb82a1311e94b49e5b662007cf5783bd1a --- /dev/null +++ b/docs/customization/keyboard-shortcuts.md @@ -0,0 +1,204 @@ +## General + +Key|Command +---|--- +`kb(workbench.action.showCommands)`, `kbstyle(F1)`|Show Command Palette +`kb(workbench.action.quickOpen)`|Quick Open +`kb(workbench.action.newWindow)`|New window/instance +`kb(workbench.action.closeWindow)`|Close window/instance + +## Basic Editing + +Key|Command +---|--- +`kb(editor.action.clipboardCutAction)`|Cut line (empty selection) +`kb(editor.action.clipboardCopyAction)`|Copy line (empty selection) +`kb(editor.action.movelinesdownAction)`|Move line down +`kb(editor.action.movelinesupAction)`|Move line up +`kb(editor.action.copylinesdownAction)`|Copy line down +`kb(editor.action.copylinesupAction)`|Copy line up +`kb(editor.action.deletelines)`|Delete line +`kb(editor.action.insertlineAfter)`|Insert line below +`kb(editor.action.insertlineBefore)`|Insert line above +`kb(editor.action.jumpToBracket)`|Jump to matching bracket +`kb(editor.action.indentlines)`|Indent line +`kb(editor.action.outdentlines)`|Outdent line +`kb(cursorHome)`|Go to beginning of line +`kb(cursorend)`|Go to end of line +`kb(cursorTop)`|Go to beginning of file +`kb(cursorBottom)`|Go to end of file +`kb(scrolllineup)`|Scroll line up +`kb(scrolllinedown)`|Scroll line down +`kb(scrollPageup)`|Scroll page up +`kb(scrollPagedown)`|Scroll page down +`kb(editor.fold)`|Fold (collapse) region +`kb(editor.unfold)`|Unfold (uncollapse) region +`kb(editor.foldRecursively)`|Fold (collapse) all subregions +`kb(editor.unfoldRecursively)`|Unfold (uncollapse) all subregions +`kb(editor.foldAll)`|Fold (collapse) all regions +`kb(editor.unfoldAll)`|Unfold (uncollapse) all regions +`kb(editor.action.addcommentline)`|Add line comment +`kb(editor.action.removecommentline)`|Remove line comment +`kb(editor.action.commentline)`|Toggle line comment +`kb(editor.action.blockcomment)`|Toggle block comment +`kb(editor.action.toggleWordWrap)`|Toggle word wrap + +## Search and Replace + +Key|Command +---|--- +`kb(actions.find)`|Find +`kb(editor.action.startFindReplaceAction)`|Replace +`kb(editor.action.nextMatchFindAction)`|Find next +`kb(editor.action.previousMatchFindAction)`|Find previous +`kb(editor.action.selectAllMatches)`|Select all occurrences of Find match +`kb(editor.action.addSelectionTonextFindMatch)`|Add selection to next Find match +`kb(editor.action.moveSelectionTonextFindMatch)`|Move last selection to next Find match +`kb(toggleFindCaseSensitive)`|Toggle Find case sensitive +`kb(toggleFindRegex)`|Toggle Find regex +`kb(toggleFindWholeWord)`|Toggle Find whole word + +## Multi-cursor and Selection + +Key|Command +---|--- +`kbstyle(Alt+Click)`|Insert cursor +`kb(editor.action.insertCursorabove)`|Insert cursor above +`kb(editor.action.insertCursorbelow)`|Insert cursor below +`kb(cursorUndo)`|Undo last cursor operation +`kb(editor.action.insertCursorAtendOfEachlineSelected)`|Insert cursor at end of each line selected +`kb(expandlineSelection)`|Select current line +`kb(editor.action.selectHighlights)`|Select all occurrences of current selection +`kb(editor.action.changeAll)`|Select all occurrences of current word +`kb(editor.action.smartSelect.expand)`|Expand selection +`kb(editor.action.smartSelect.shrink)`|Shrink selection +`kbstyle(Shift+Alt)` + drag mouse |Column selection +`kb(cursorColumnSelectup)`|Column selection up +`kb(cursorColumnSelectdown)`|Column selection down +`kb(cursorColumnSelectLeft)`|Column selection left +`kb(cursorColumnSelectRight)`|Column selection right +`kb(cursorColumnSelectPageup)`|Column selection page up +`kb(cursorColumnSelectPagedown)`|Column selection page down + +## Rich Languages Editing + +Key|Command +---|--- +`kb(editor.action.triggerSuggest)`|Trigger suggestion +`kb(editor.action.triggerParameterHints)`|Trigger parameter hints +`kb(editor.action.formatDocument)`|Format document +`kb(editor.action.formatSelection)`|Format selection +`kb(editor.action.revealDefinition)`|Go to Definition +`kb(editor.action.peekDefinition)`|Peek Definition +`kb(editor.action.revealDefinitionAside)`|Open Definition to the side +`kb(editor.action.quickFix)`|Quick Fix +`kb(editor.action.referenceSearch.trigger)`|Peek References +`kb(editor.action.rename)`|Rename Symbol +`kb(editor.action.inPlaceReplace.down)`|Replace with next value +`kb(editor.action.inPlaceReplace.up)`|Replace with previous value +`kb(editor.action.trimTrailingWhitespace)`|Trim trailing whitespace +`kb(workbench.action.editor.changeLanguageMode)`|Change file language + +## Navigation + +Key|Command +---|--- +`kb(workbench.action.showAllSymbols)`|Show all Symbols +`kb(workbench.action.gotoline)`|Go to Line... +`kb(workbench.action.quickOpen)`|Go to File... +`kb(workbench.action.gotoSymbol)`|Go to Symbol... +`kb(workbench.actions.view.problems)`|Show Problems panel +`kb(editor.action.marker.nextInFiles)`|Go to next error or warning +`kb(editor.action.marker.prevInFiles)`|Go to previous error or warning +`kb(workbench.action.openpreviousRecentlyUsedEditorInGroup)`|Navigate editor group history +`kb(workbench.action.navigateBack)`|Go back +`kb(workbench.action.quickInputBack)`|Go back to previous step, when in the QuickInput UI +`kb(workbench.action.navigateForward)`|Go forward +`kb(editor.action.toggleTabFocusMode)`|Toggle Tab moves focus + +## Editor Management + +Key|Command +---|--- +`kb(workbench.action.closeActiveEditor)`, `kbstyle(Ctrl+W)`|Close editor +`kb(workbench.action.closeFolder)`|Close folder +`kb(workbench.action.splitEditor)`|Split editor +`kb(workbench.action.focusFirstEditorGroup)`|Focus into first editor group +`kb(workbench.action.focusSecondEditorGroup)`|Focus into second editor group +`kb(workbench.action.focusThirdEditorGroup)`|Focus into third editor group +`kb(workbench.action.focuspreviousGroup)`|Focus into previous editor group +`kb(workbench.action.focusnextGroup)`|Focus into next editor group +`kb(workbench.action.moveEditorLeftInGroup)`| Move editor left +`kb(workbench.action.moveEditorRightInGroup)`| Move editor right +`kb(workbench.action.moveActiveEditorGroupLeft)`|Move active editor group left/up +`kb(workbench.action.moveActiveEditorGroupRight)`|Move active editor group right/down + +## File Management + +Key|Command +---|--- +`kb(workbench.action.files.newUntitledfile)`|New File +`kb(workbench.action.files.openfile)`|Open File... +`kb(workbench.action.files.openFileFolder)`|Open File... (macOS) +`kb(workbench.action.files.save)`|Save +`kb(workbench.action.files.saveAs)`|Save As... +`kb(workbench.action.files.saveAll)`|Save All +`kb(workbench.action.closeActiveEditor)`|Close +`kb(workbench.action.closeAllEditors)`|Close All +`kb(workbench.action.reopenClosedEditor)`|Reopen closed editor +`kb(workbench.action.keepEditor)`|Keep Open +`kb(workbench.action.opennextRecentlyUsedEditorInGroup)`|Open next +`kb(workbench.action.openpreviousRecentlyUsedEditorInGroup)`|Open previous +`kb(workbench.action.files.copyPathOfActivefile)`|Copy path of active file +`kb(workbench.action.files.revealActivefileInWindows)`|Reveal active file in Explorer +`kb(workbench.action.files.showOpenedfileInNewWindow)`|Show active file in new window/instance + +## Display + +Key|Command +---|--- +`kb(workbench.action.toggleFullScreen)`|Toggle full screen +`kb(workbench.action.toggleEditorGroupLayout)`|Toggle editor layout +`kb(workbench.action.zoomIn)`|Zoom in +`kb(workbench.action.zoomOut)`|Zoom out +`kb(workbench.action.toggleSidebarVisibility)`|Toggle Sidebar visibility +`kb(workbench.view.explorer)`|Show Explorer / Toggle focus +`kb(workbench.view.search)`|Show Search +`kb(workbench.view.scm)`|Show Source Control +`kb(workbench.view.debug)`|Show Debug +`kb(workbench.view.extensions)`|Show Extensions +`kb(workbench.action.replaceInfiles)`|Replace in files +`kb(workbench.action.search.toggleQueryDetails)`|Toggle Search details +`kb(workbench.action.terminal.openNativeConsole)`|Open new command prompt/terminal +`kb(workbench.action.output.toggleOutput)`|Show Output panel +`kb(markdown.showPreview)`|Toggle Markdown preview +`kb(markdown.showPreviewToSide)`|Open Markdown preview to the side + +## Debug + +Key|Command +---|--- +`kb(editor.debug.action.toggleBreakpoint)`|Toggle breakpoint +`kb(workbench.action.debug.start)`|Start +`kb(workbench.action.debug.continue)`|Continue +`kb(workbench.action.debug.stepInto)`|Step into +`kb(workbench.action.debug.stepOut)`|Step out +`kb(workbench.action.debug.stepOver)`|Step over +`kb(workbench.action.debug.stop)`|Stop +`kb(editor.action.showHover)`|Show hover + +## Integrated Terminal + +Key|Command +---|--- +`kb(workbench.action.terminal.toggleTerminal)`|Show integrated terminal +`kb(workbench.action.terminal.new)`|Create new terminal +`kb(workbench.action.terminal.copySelection)`|Copy selection +`kb(workbench.action.terminal.paste)`|Paste into active terminal +`kb(workbench.action.terminal.scrollup)`|Scroll up +`kb(workbench.action.terminal.scrolldown)`|Scroll down +`kb(workbench.action.terminal.scrollupPage)`|Scroll page up +`kb(workbench.action.terminal.scrolldownPage)`|Scroll page down +`kb(workbench.action.terminal.scrollToTop)`|Scroll to top +`kb(workbench.action.terminal.scrollToBottom)`|Scroll to bottom + diff --git a/docs/editor/accessibility.md b/docs/editor/accessibility.md new file mode 100644 index 0000000000000000000000000000000000000000..fbe2a94bfb5fde6968cdaf243b9fd9bfb530b15e --- /dev/null +++ b/docs/editor/accessibility.md @@ -0,0 +1,119 @@ +--- +Order: 16 +Area: editor +TOCTitle: Accessibility +ContentId: 62894B41-CC33-400A-8A56-8C761C77B4C7 +PageTitle: Accessibility in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code user accessibility features. Learn here about the various ways VS Code aids user accessibility. +--- +# Accessibility + +Visual Studio Code has many features to help make the editor accessible to all users. Zoom and High Contrast colors improve editor visibility, keyboard-only navigation allows use without a mouse, and the editor has been optimized for screen readers. + +## Zoom + +You can increase the Zoom level in VS Code with the **View** > **Zoom In** command (`kb(workbench.action.zoomIn)`). The zoom level increases by 20% each time the command is executed. The **View** > **Zoom Out** (`kb(workbench.action.zoomOut)`) command lets you decrease the Zoom level. + +![Zoomed in editor](images/accessibility/zoomed-in.png) + +### Persisted Zoom Level + +When you adjust the zoom level with the **View** > **Zoom In / Out** commands, the zoom level is persisted in the `window.zoomLevel` [setting](/docs/getstarted/settings.md). The default value is 0 and each increment increases the zoom level by 20%. + +## High Contrast theme + +We support a High Contrast color theme on all platforms. Use **File** > **Preferences** > **Color Theme** (`kb(workbench.action.selectTheme)`) to display the **Select Color Theme** drop-down and select the **High Contrast** theme. + +![High Contrast Theme](images/accessibility/high-contrast.png) + +## Keyboard navigation + +You will find that VS Code provides an exhaustive list of commands in the **Command Palette** (`kb(workbench.action.showCommands)`) so that you can run VS Code without using the mouse. Press `kb(workbench.action.showCommands)` then type a command name (for example 'git') to filter the list of commands. + +VS Code also has many preset keyboard shortcuts for commands. These are displayed to the right of the command in the **Command Palette**. + +![Keyboard shortcuts in Command Palette](images/accessibility/keyboard-shortcuts.png) + +You can also set your own keyboard shortcuts. **File** > **Preferences** > **Keyboard Shortcuts** (`kb(workbench.action.openGlobalKeybindings)`) brings up the Keyboard Shortcuts editor where you can discover and modify keybindings for VS Code actions. See [Key Bindings](/docs/getstarted/keybindings.md) for more details on customizing or adding your own keyboard shortcuts. + +## Tab navigation + +You can use the `kbstyle(Tab)` key to jump between VS Code UI controls. Use `kbstyle(Shift+Tab)` to tab in reverse order. As you tab through the UI controls, you can see an indicator around the UI element once the element gains focus. + +Some areas that support Tab navigation are: + +* The View switcher (File Explorer, Search, Source Control, Debug, Extensions) +* The header of collapsible sections in a view to expand/collapse +* Actions in views and sections +* Actions for items in the tree + +## Tab trapping + +By default, pressing the `kbstyle(Tab)` within a source code file inserts the Tab character (or spaces depending on your Indentation setting) and does not leave the open file. You can toggle the trapping of `kbstyle(Tab)` with `kb(editor.action.toggleTabFocusMode)` and subsequent `kbstyle(Tab)` keys will move focus out of the file. When default `kbstyle(Tab)` trapping is off, you will see an indicator in the Status Bar. + +![tab moves focus](images/accessibility/tab-moves-focus.png) + +You can also toggle `kbstyle(Tab)` trapping from the **Command Palette** (`kb(workbench.action.showCommands)`) with the **Toggle Tab Key Moves Focus** action. + +Read-only files never trap the `kbstyle(Tab)` key. The **Integrated Terminal** panel respects the `kbstyle(Tab)` trapping mode and can be toggled with `kb(editor.action.toggleTabFocusMode)`. + +## Screen readers + +VS Code supports screen readers in the editor using a strategy based on paging the text. We have tested using the [NVDA screen reader](https://www.nvaccess.org), but we expect all screen readers to benefit from this support. + +> When using NVDA on Windows, we recommend to update to NVDA 2017.3 or higher. NVDA 2017.3 increases NVDA's timeout for receiving a caret move event from 30ms to 100ms. This version is the first one [where the built-in timeout is increased from 30ms to 100ms](https://github.com/nvaccess/nvda/pull/7201). + +The **Go to Next/Previous Error or Warning** actions (`kb(editor.action.marker.nextInFiles)` and `kb(editor.action.marker.prevInFiles)`) allow screen readers to announce the error or warning messages. + +When the suggestions pop up, they will get announced to screen readers. It is possible to navigate the suggestions using `kbstyle(Ctrl+Up)` and `kbstyle(Ctrl+Down)`, you can dismiss the suggestions with `kbstyle(Shift+Escape)` and if suggestions get in your way, you can disable the auto-popup of suggestions with the `editor.quickSuggestions` setting. + +The **Go to Next/Previous Difference** actions (`kb(editor.action.diffReview.next)` and `kb(editor.action.diffReview.prev)`), when in a diff editor pane, will bring up the Diff Review pane, which allows the navigation of the diffs, presented in a unified patch format. Arrow Up and Arrow Down can be used to navigate through the unchanged, inserted or deleted lines. Pressing `kbstyle(Enter)` will return focus to the modified pane of the diff editor at the selected line number (or closest still existing line number in case a deleted line is selected). Use `kbstyle(Escape)` or `kb(Shift+Escape)` to dismiss the Diff Review pane. + +## Accessibility help + +You can press `kb(editor.action.showAccessibilityHelp)` to trigger the **Show Accessibility Help** dialog while in an editor to check the state of various accessibility options in VS Code: + +![accessibility status](images/accessibility/status.png) + +## Screen reader mode + +When VS Code detects that a screen reader is being used, it goes into screen reader optimized mode for the UI such as the editor and Integrated Terminal. The Status Bar displays **Screen Reader Optimized** in the lower right and you can exit screen reader mode by clicking on the display text. + +![screen reader optimized mode](images/accessibility/screen-reader-mode.png) + +Certain features such as folding, minimap (code overview), and word wrap are disabled when in screen reader mode. You can control whether VS Code uses screen reader mode with the **Editor: Accessibility Support** setting (`editor.accessibilitySupport`) and the values are `on`, `off`, or the default `auto` to automatically detect a screen reader through querying the platform. + +## Terminal accessibility + +Output in the Integrated Terminal can be navigated through by using the scroll commands available in the Command Palette (press `kbstyle(F1)` and search for "Terminal Scroll"). + +## Debugger accessibility + +The VS Code debugger UI is user accessible and has the following features: + +* Changes in debug state are read out (for example 'started', 'breakpoint hit', 'terminated', ...). +* All debug actions are keyboard accessible. +* Both the Debug View and Debug Console support Tab navigation. +* Debug hover is keyboard accessible (`kb(editor.action.showHover)`). +* Keyboard shortcuts can be created to set focus to each debugger area. + +## Current known issues + +VS Code has some known accessibility issues depending on the platform. + +### macOS + +There is limited screen reader support for the editor with VoiceOver. + +### Linux + +There is no screen reader support for the editor. This is because there is no accessibility implementation for Chrome on Linux. + +## Next steps + +Read on to find out about: + +* [Visual Studio Code User Interface](/docs/getstarted/userinterface.md) - A quick orientation to VS Code. +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. diff --git a/docs/editor/codebasics.md b/docs/editor/codebasics.md new file mode 100644 index 0000000000000000000000000000000000000000..f6b8f662056d7ca6fc4df9f9fef63523469023b3 --- /dev/null +++ b/docs/editor/codebasics.md @@ -0,0 +1,308 @@ +--- +Order: 2 +Area: editor +TOCTitle: Basic Editing +ContentId: DE4EAE2F-4542-4363-BB74-BE47D64141E6 +PageTitle: Basic Editing in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Learn about the basic editing features of Visual Studio Code. Search, multiple selection, code formatting. +MetaSocialImage: codebasics_CodeBasics.png +--- +# Basic Editing + +Visual Studio Code is an editor first and foremost and includes the features you need for highly productive source code editing. This topic takes you through the basics of the editor and helps you get moving with your code. + +## Keyboard shortcuts + +Being able to keep your hands on the keyboard when writing code is crucial for high productivity. VS Code has a rich set of default keyboard shortcuts as well as allowing you to customize them. + +* [Keyboard Shortcuts Reference](/docs/getstarted/keybindings.md#keyboard-shortcuts-reference) - Learn the most commonly used and popular keyboard shortcuts by downloading the reference sheet. +* [Install a Keymap extension](/docs/getstarted/keybindings.md#keymap-extensions) - Use the keyboard shortcuts of your old editor (such as Sublime Text, Atom, and Vim) in VS Code by installing a Keymap extension. +* [Customize Keyboard Shortcuts](/docs/getstarted/keybindings.md#customizing-shortcuts) - Change the default keyboard shortcuts to fit your style. + +## Multiple selections (multi-cursor) + +VS Code supports multiple cursors for fast simultaneous edits. You can add secondary cursors (rendered thinner) with `kbstyle(Alt+Click)`. Each cursor operates independently based on the context it sits in. A common way to add more cursors is with `kb(editor.action.insertCursorBelow)` or `kb(editor.action.insertCursorAbove)` that insert cursors below or above. + +> **Note:** Your graphics card driver (for example NVIDIA) might overwrite these default shortcuts. + +![Multi-cursor](images/codebasics/multicursor.gif) + +`kb(editor.action.addSelectionToNextFindMatch)` selects the word at the cursor, or the next occurrence of the current selection. + +![Multi-cursor-next-word](images/codebasics/multicursor-word.gif) + +> **Tip:** You can also add more cursors with `kb(editor.action.selectHighlights)`, which will add a selection at each occurrence of the current selected text. + +### Multi-cursor modifier + +If you'd like to change the modifier key for applying multiple cursors to `kbstyle(Cmd+Click)` on macOS and `kbstyle(Ctrl+Click)` on Windows and Linux, you can do so with the `editor.multiCursorModifier` [setting](/docs/getstarted/settings.md). This lets users coming from other editors such as Sublime Text or Atom continue to use the keyboard modifier they are familiar with. + +The setting can be set to: + +* `ctrlCmd` - Maps to `kbstyle(Ctrl)` on Windows and `kbstyle(Cmd)` on macOS. +* `alt` - The existing default `kbstyle(Alt)`. + +There's also a menu item **Use Ctrl+Click for Multi-Cursor** in the **Selection** menu to quickly toggle this setting. + +The **Go To Definition** and **Open Link** gestures will also respect this setting and adapt such that they do not conflict. For example, when the setting is `ctrlCmd`, multiple cursors can be added with `kbstyle(Ctrl/Cmd+Click)`, and opening links or going to definition can be invoked with `kbstyle(Alt+Click)`. + +### Shrink/expand selection + +Quickly shrink or expand the current selection. Trigger it with `kb(editor.action.smartSelect.shrink)` and `kb(editor.action.smartSelect.expand)`. + +Here's an example of expanding the selection with `kb(editor.action.smartSelect.expand)`: + +![Expand selection](images/codebasics/expandselection.gif) + +## Column (box) selection + +Place the cursor in one corner and then hold `kbstyle(Shift+Alt)` while dragging to the opposite corner: + +![Column text selection](images/codebasics/column-select.gif) + +Note: This changes to `kbstyle(Shift+Ctrl/Cmd)` when using `kbstyle(Ctrl/Cmd)` as [multi-cursor modifier](#multi-cursor-modifier). + +There are also default key bindings for column selection on macOS and Windows, but not on Linux. + +Key|Command|Command id +---|-------|---------- +`kb(cursorColumnSelectDown)`|Column Select Down|`cursorColumnSelectDown` +`kb(cursorColumnSelectUp)`|Column Select Up|`cursorColumnSelectUp` +`kb(cursorColumnSelectLeft)`|Column Select Left|`cursorColumnSelectLeft` +`kb(cursorColumnSelectRight)`|Column Select Right|`cursorColumnSelectRight` +`kb(cursorColumnSelectPageDown)`|Column Select Page Down|`cursorColumnSelectPageDown` +`kb(cursorColumnSelectPageUp)`|Column Select Page Up|`cursorColumnSelectPageUp` + +You can [edit](/docs/getstarted/keybindings.md) your `keybindings.json` to bind them to something more familiar if you wish. + +## Save / Auto Save + +By default, VS Code requires an explicit action to save your changes to disk, `kb(workbench.action.files.save)`. + +However, it's easy to turn on `Auto Save`, which will save your changes after a configured delay or when focus leaves the editor. With this option turned on, there is no need to explicitly save the file. The easiest way to turn on `Auto Save` is with the **File** > **Auto Save** toggle which turns on and off save after a delay. + +For more control over `Auto Save`, open User or Workspace [settings](/docs/getstarted/settings.md) and find the associated settings: + +* `files.autoSave`: Can have the values: + * `off` - to disable auto save. + * `afterDelay` - to save files after a configured delay (default 1000 ms). + * `onFocusChange` - to save files when focus moves out of the editor of the dirty file. + * `onWindowChange` - to save files when the focus moves out of the VS Code window. +* `files.autoSaveDelay`: Configures the delay in milliseconds when `files.autoSave` is configured to `afterDelay`. The default is 1000 ms. + +## Hot Exit + +VS Code will remember unsaved changes to files when you exit by default. Hot exit is triggered when the application is closed via **File** > **Exit** (**Code** > **Quit** on macOS) or when the last window is closed. + +You can configure hot exit by setting `files.hotExit` to the following values: + +* `"off"`: Disable hot exit. +* `"onExit"`: Hot exit will be triggered when the application is closed, that is when the last window is closed on Windows/Linux or when the `workbench.action.quit` command is triggered (from the **Command Palette**, keyboard shortcut or menu). All windows with backups will be restored upon next launch. +* `"onExitAndWindowClose"`: Hot exit will be triggered when the application is closed, that is when the last window is closed on Windows/Linux or when the `workbench.action.quit` command is triggered (from the **Command Palette**, keyboard shortcut or menu), and also for any window with a folder opened regardless of whether it is the last window. All windows without folders opened will be restored upon next launch. To restore folder windows as they were before shutdown, set `window.restoreWindows` to `all`. + +## Search across files + +VS Code allows you to quickly search over all files in the currently opened folder. Press `kb(workbench.view.search)` and enter your search term. Search results are grouped into files containing the search term, with an indication of the hits in each file and its location. Expand a file to see a preview of all of the hits within that file. Then single-click on one of the hits to view it in the editor. + +![A simple text search across files](images/codebasics/search.png) + +>**Tip:** We support regular expression searching in the search box, too. + +You can configure advanced search options by clicking the ellipsis (**Toggle Search Details**) below the search box on the right (or press `kb(workbench.action.search.toggleQueryDetails)`). This will show additional fields to configure the search. + +### Advanced search options + +![Advanced search options](images/codebasics/searchadvanced.png) + +In the input box below the search box, you can enter patterns to include or exclude from the search. If you enter `example`, that will match every folder and file named `example` in the workspace. If you enter `./example`, that will match the folder `example/` at the top level of your workspace. Use `!` to exclude those patterns from the search. `!example` will skip searching any folder or file named `example`. You can also use glob syntax: + +* `*` to match one or more characters in a path segment +* `?` to match on one character in a path segment +* `**` to match any number of path segments, including none +* `{}` to group conditions (e.g. `{**/*.html,**/*.txt}` matches all HTML and text files) +* `[]` to declare a range of characters to match (e.g., `example.[0-9]` to match on `example.0`, `example.1`, …) + +VS Code excludes some folders by default to reduce the number of search results that you are not interested in (for example: `node_modules`). Open [settings](/docs/getstarted/settings.md) to change these rules under the `files.exclude` and `search.exclude` section. + +Also note the **Use Exclude Settings and Ignore Files** toggle button in the **files to exclude** box. The toggle determines whether to exclude files that are ignored by your `.gitignore` files and/or matched by your `files.exclude` and `search.exclude` settings. + +>**Tip:** From the Explorer, you can right-click on a folder and select **Find in Folder** to search inside a folder only. + +VS Code does support regular expression searches, however, [backreferences](https://www.regular-expressions.info/backref.html) and [lookaround](https://www.regular-expressions.info/lookaround.html) aren't supported by default. But you can enable these with the setting `search.usePCRE2`. This configures [ripgrep](https://github.com/BurntSushi/ripgrep) to use the [PCRE2](https://pcre.org/) regex engine. While PCRE2 supports many other features, we only support regex expressions that are still valid in JavaScript, because open editors are still searched using the editor's JavaScript-based search. + +### Search and replace + +You can also Search and Replace across files. Expand the Search widget to display the Replace text box. + +![search and replace](images/codebasics/global-search-replace.png) + +When you type text into the Replace text box, you will see a diff display of the pending changes. You can replace across all files from the Replace text box, replace all in one file or replace a single change. + +![search and replace diff view](images/codebasics/search-replace-example.png) + +>**Tip:** You can quickly reuse a previous search term by using `kb(history.showNext)` and `kb(history.showPrevious)` to navigate through your search term history. + +## IntelliSense + +We'll always offer word completion, but for the rich [languages](/docs/languages/overview.md), such as JavaScript, JSON, HTML, CSS, SCSS, Less, C# and TypeScript, we offer a true IntelliSense experience. If a language service knows possible completions, the IntelliSense suggestions will pop up as you type. You can always manually trigger it with `kb(editor.action.triggerSuggest)`. By default, `kbstyle(Tab)` or `kbstyle(Enter)` are the accept keyboard triggers but you can also [customize these key bindings](/docs/getstarted/keybindings.md). + +> **Tip:** The suggestions filtering supports CamelCase so you can type the letters which are upper cased in a method name to limit the suggestions. For example, "cra" will quickly bring up "createApplication". + +> **Tip:** IntelliSense suggestions can be configured via the `editor.quickSuggestions` and `editor.suggestOnTriggerCharacters` [settings](/docs/getstarted/settings.md). + +JavaScript and TypeScript developers can take advantage of the [npmjs](https://www.npmjs.com) type declaration (typings) file repository to get IntelliSense for common JavaScript libraries (Node.js, React, Angular). You can find a good explanation on using type declaration files in the [JavaScript language](/docs/languages/javascript.md#intellisense) topic and the [Node.js](/docs/nodejs/nodejs-tutorial.md) tutorial. + +Learn more in the [IntelliSense document](/docs/editor/intellisense.md). + +## Formatting + +VS Code has great support for source code formatting. The editor has two explicit format actions: + +* **Format Document** (`kb(editor.action.formatDocument)`) - Format the entire active file. +* **Format Selection** (`kb(editor.action.formatSelection)`) - Format the selected text. + +You can invoke these from the **Command Palette** (`kb(workbench.action.showCommands)`) or the editor context menu. + +VS Code has default formatters for JavaScript, TypeScript, JSON, and HTML. Each language has specific formatting options (for example, `html.format.indentInnerHtml`) which you can tune to your preference in your user or workspace [settings](/docs/getstarted/settings.md). You can also disable the default language formatter if you have another extension installed that provides formatting for the same language. + +```json +"html.format.enable": false +``` + +Along with manually invoking code formatting, you can also trigger formatting based on user gestures such as typing, saving or pasting. These are off by default but you can enable these behaviors through the following [settings](/docs/getstarted/settings.md): + +* `editor.formatOnType` - Format the line after typing. +* `editor.formatOnSave` - Format a file on save. +* `editor.formatOnPaste` - Format the pasted content. + +>Note: Not all formatters support format on paste as to do so they must support formatting a selection or range of text. + +In addition to the default formatters, you can find extensions on the Marketplace to support other languages or formatting tools. There is a `Formatters` category so you can easily search and find [formatting extensions](https://marketplace.visualstudio.com/search?target=VSCode&category=Formatters&sortBy=Downloads). In the **Extensions** view search box, type 'formatters' or 'category:formatters' to see a filtered list of extensions within VS Code. + +## Folding + +You can fold regions of source code using the folding icons on the gutter between line numbers and line start. Move the mouse over the gutter and click to fold and unfold regions. Use `kbstyle(Shift + Click)` on the folding icon to fold or unfold the region and all regions inside. + +![Folding](images/codebasics/folding.png) + +You can also use the following actions: + +* Fold (`kb(editor.fold)`) folds the innermost un-collapsed region at the cursor. +* Unfold (`kb(editor.unfold)`) unfolds the collapsed region at the cursor. +* Fold Recursively (`kb(editor.foldRecursively)`) folds the innermost un-collapsed region at the cursor and all regions inside that region. +* Unfold Recursively (`kb(editor.unfoldRecursively)`) unfolds the region at the cursor and all regions inside that region. +* Fold All (`kb(editor.foldAll)`) folds all regions in the editor. +* Unfold All (`kb(editor.unfoldAll)`) unfolds all regions in the editor. +* Fold Level X (`kb(editor.foldLevel2)` for level 2) folds all regions of level X, except the region at the current cursor position. +* Fold All Block Comments (`kb(editor.foldAllBlockComments)`) folds all regions that start with a block comment token. + +Folding ranges are by default evaluated based on the indentation of lines. A folding range starts when a line has a smaller indent than one or more following lines, and ends when there is a line with the same or smaller indent. + +Since the 1.22 release, folding ranges can also be computed based on syntax tokens of the editor's configured language. The following languages already provide syntax aware folding: +- Markdown, HTML, CSS, LESS, SCSS and JSON + +If you prefer to switch back to indentation based folding for one (or all) of the languages above, use: + +```json + "[html]": { + "editor.foldingStrategy": "indentation" + }, +``` + +Regions can also be defined by markers defined by each language. The following languages currently have markers defined: + +* C#: `#region` and `#endregion` +* C/C++: `#pragma region` and `#pragma endregion` +* CSS/Less/SCSS: `/*#region*/` and `/*#endregion*/` +* Coffeescript: `#region` and `#endregion` +* F#: `//#region` and `//#endregion` and `(#region)` and `(#endregion)` +* Java: `//#region` and `// #endregion` and `//` and `//` +* HTML: +* PHP: `#region` and `#endregion` +* Powershell: `#region` and `#endregion` +* Python: `#region` and `#endregion` +* TypeScript/JavaScript: `//#region` and `//#endregion` and `//region` and `//endregion` +* VB: `#Region` and `#End Region` +* Bat: `::#region` and `::#endregion` +* Markdown: `` and `` + +To fold and unfold only the regions defined by markers use: + +* Fold Marker Regions (`kb(editor.foldAllMarkerRegions)`) folds all marker regions. +* Unfold Marker Regions (`kb(editor.unfoldAllMarkerRegions)`) unfolds all marker regions. + +## Indentation + +VS Code lets you control text indentation and whether you'd like to use spaces or tab stops. By default, VS Code inserts spaces and uses 4 spaces per `kbstyle(Tab)` key. If you'd like to use another default, you can modify the `editor.insertSpaces` and `editor.tabSize` [settings](/docs/getstarted/settings.md). + +```json + "editor.insertSpaces": true, + "editor.tabSize": 4, +``` + +### Auto-detection + +VS Code analyzes your open file and determines the indentation used in the document. The auto-detected indentation overrides your default indentation settings. The detected setting is displayed on the right side of the Status Bar: + +![auto detect indentation](images/codebasics/indentation-detection.png) + +You can click on the Status Bar indentation display to bring up a drop-down with indentation commands allowing you to change the default settings for the open file or convert between tab stops and spaces. + +![indentation commands](images/codebasics/indentation-commands.png) + +>**Note:** VS Code auto-detection checks for indentations of 2, 4, 6 or 8 spaces. If your file uses a different number of spaces, the indentation may not be correctly detected. For example, if your convention is to indent with 3 spaces, you may want to turn off `editor.detectIndentation` and explicitly set the tab size to 3. + +```json + "editor.detectIndentation": false, + "editor.tabSize": 3, +``` + +## File encoding support + +Set the file encoding globally or per workspace by using the `files.encoding` setting in **User Settings** or **Workspace Settings**. + +![files.encoding setting](images/codebasics/filesencodingsetting.png) + +You can view the file encoding in the status bar. + +![Encoding in status bar](images/codebasics/fileencoding.png) + +Click on the encoding button in the status bar to reopen or save the active file with a different encoding. + +![Reopen or save with a different encoding](images/codebasics/encodingclicked.png) + +Then choose an encoding. + +![Select an encoding](images/codebasics/encodingselection.png) + +## Next steps + +You've covered the basic user interface - there is a lot more to VS Code. Read on to find out about: + +* [Intro Video - Setup and Basics](/docs/introvideos/basics.md) - Watch a tutorial on the basics of VS Code. +* [User/Workspace Settings](/docs/getstarted/settings.md) - Learn how to configure VS Code to your preferences through user and workspace settings. +* [Code Navigation](/docs/editor/editingevolved.md) - Peek and Goto Definition, and more. +* [Integrated Terminal](/docs/editor/integrated-terminal.md) - Learn about the integrated terminal for quickly performing command line tasks from within VS Code. +* [IntelliSense](/docs/editor/intellisense.md) - VS Code brings smart code completions. +* [Debugging](/docs/editor/debugging.md) - This is where VS Code really shines. + +## Common questions + +### Is it possible to globally search and replace? + +Yes, expand the Search view text box to include a replace text field. You can search and replace across all the files in your workspace. Note that if you did not open VS Code on a folder, the search will only run on the currently open files. + +![global search and replace](images/codebasics/global-search-replace.png) + +### How do I turn on word wrap? + +You can control word wrap through the `editor.wordWrap` [setting](/docs/getstarted/settings.md). By default, `editor.wordWrap` is `off` but if you set to it to `on`, text will wrap on the editor's viewport width. + +```json + "editor.wordWrap": "on" +``` + +You can toggle word wrap for the VS Code session with `kb(editor.action.toggleWordWrap)`. + +You can also add vertical column rulers to the editor with the `editor.rulers` setting which takes an array of column character positions where you'd like vertical rulers. diff --git a/docs/editor/command-line.md b/docs/editor/command-line.md new file mode 100644 index 0000000000000000000000000000000000000000..d393c3158f7df87b336e164bc685751d772118fc --- /dev/null +++ b/docs/editor/command-line.md @@ -0,0 +1,155 @@ +--- +Order: 15 +Area: editor +TOCTitle: Command Line +ContentId: 8faef870-7a5f-4070-ad17-8ba791006912 +PageTitle: The Visual Studio Code Command Line Options +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code command line options (switches). +--- +# Command Line Interface (CLI) + +Visual Studio Code has a powerful command line interface that lets you control how you launch the editor. You can open files, install extensions, change the display language, and output diagnostics through command line options (switches). + +![command line example](images/command-line/hero.png) + +If you are looking for how to run command line tools inside VS Code, see the [Integrated Terminal](/docs/editor/integrated-terminal.md). + +## Launching from command line + +You can launch VS Code from the command line to quickly open a file, folder, or project. Typically, you open VS Code within the context of a folder. To do this, from an open terminal or command prompt, navigate to your project folder and type `code .`: + +![launch VS Code](images/command-line/launch-vscode.png) + +**Note:** Users on macOS must first run a command (**Shell Command: Install 'code' command in PATH**) to add VS Code executable to the `PATH` environment variable. Read the [macOS setup guide](/docs/setup/mac.md) for help. + +Windows and Linux installations should add the VS Code binaries location to your system path. If this isn't the case, you can manually add the location to the `Path` environment variable (`$PATH` on Linux). For example, on Windows, VS Code is installed under `AppData\Local\Programs\Microsoft VS Code\bin`. To review platform specific setup instructions, see [Setup](/docs/setup/setup-overview.md). + +> **Insiders:** If you are using the VS Code [Insiders](/insiders) preview, you launch your Insiders build with `code-insiders`. + +## Core CLI options + +Here are optional arguments you can use when starting VS Code at the command line via `code`: + +Argument|Description +------------------|----------- +`-h` or `--help` | Print usage +`-v` or `--version` | Print VS Code version (for example, 1.22.2), GitHub commit id, and architecture (for example, x64). +`-n` or `--new-window`| Opens a new session of VS Code instead of restoring the previous session (default). +`-r` or `--reuse-window` | Forces opening a file or folder in the last active window. +`-g` or `--goto` | When used with *file:line[:character]*, opens a file at a specific line and optional character position. This argument is provided since some operating systems permit `:` in a file name. +`-d` or `--diff` | Open a file difference editor. Requires two file paths as arguments. +`-w` or `--wait` | Wait for the files to be closed before returning. +`--locale ` | Set the [display language](/docs/getstarted/locales.md) (locale) for the VS Code session. (for example, `en-US` or `zh-TW`) + +![launch with locale](images/command-line/launch-locale.png) + +## Opening Files and Folders + +Sometimes you will want to open or create a file. If the specified file does not exist, VS Code will create them for you along with any new intermediate folders: + +```bash +code index.html style.css documentation\readme.md +``` + +For both files and folders, you can use absolute or relative paths. Relative paths are relative to the current directory of the command prompt where you run `code`. + +If you specify more than one file at the command line, VS Code will open only a single instance. + +If you specify more than one folder at the command line, VS Code will create a [Multi-root Workspace](/docs/editor/multi-root-workspaces.md) including each folder. + +Argument|Description +------------------|----------- +`file` | Name of a file to open. If the file doesn't exist, it will be created and marked as edited. You can specify multiple files by separating each file name with a space. +`file:line[:character]` | Used with the `-g` argument. Name of a file to open at the specified line and optional character position. You can specify multiple files in this manner, but you must use the `-g` argument (once) before using the `file:line[:character]` specifier. +`folder` | Name of a folder to open. You can specify multiple folders and a new [Multi-root Workspace](/docs/editor/multi-root-workspaces.md) is created. + +![go to line and column](images/command-line/goto-line-column.png) + +## Working with extensions + +You can install and manage VS Code [extensions](/docs/editor/extension-gallery.md) from the command line. + +Argument|Description +------------------|----------- +`--install-extension ` | Install an extension. Provide the full extension name `publisher.extension` as an argument. Use `--force` argument to avoid prompts. +`--uninstall-extension ` | Uninstall an extension. Provide the full extension name `publisher.extension` as an argument. +`--disable-extensions` | Disable all installed extensions. Extensions will still be visible in the **Disabled** section of the Extensions view but they will never be activated. +`--list-extensions` | List the installed extensions. +`--show-versions` | Show versions of installed extensions, when using `--list-extensions` +`--enable-proposed-api ` | Enables proposed api features for an extension. Provide the full extension name `publisher.extension` as an argument. + +![install extension](images/command-line/install-extension.png) + +## Advanced CLI options + +There are several CLI options that help with reproducing errors and advanced setup. + +Argument|Description +------------------|----------- +`--extensions-dir ` | Set the root path for extensions. +`--user-data-dir ` | Specifies the directory that user data is kept in, useful when running as root. +`-s, --status` | Print process usage and diagnostics information. +`-p, --performance` | Start with the **Developer: Startup Performance** command enabled. +`--disable-gpu` | Disable GPU hardware acceleration. +`--verbose` | Print verbose output (implies `--wait`). +`--prof-startup` | Run CPU profiler during startup. +`--upload-logs` | Uploads logs from current session to a secure endpoint. +**Multi-root**| +`--add ` | Add folder(s) to the last active window for a multi-root workspace. + +## Opening VS Code with URLs + +On Windows and macOS, you can also open projects and files using the platform's URL handling mechanism. Use the following URL formats to: + +Open a project + +```bash +vscode://file/{full path to project}/ + +vscode://file/c:/myProject/ +``` + +Open a file + +```bash +vscode://file/{full path to file} + +vscode://file/c:/myProject/package.json +``` + +Open a file to line and column + +```bash +vscode://file/{full path to file}:line:column + +vscode://file/c:/myProject/package.json:5:10 +``` + +You can use the URL in applications such as browsers or file explorers that can parse and redirect the URL. For example, on Windows, you could pass a `vscode://` URL directly to the Windows Explorer or to the command line as `start vscode://{full path to file}`. + +![vscode url in Windows Explorer](images/command-line/vscode-url.png) + +## Next steps + +Read on to find out about: + +* [Integrated Terminal](/docs/editor/integrated-terminal.md) - Run command line tools from inside VS Code. +* [Basic Editing](/docs/editor/codebasics.md) - Learn the basics of the VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - VS Code lets you quickly understand and move through your source code. + +## Common questions + +### 'code' is not recognized as an internal or external command + +Your OS can not find the VS Code binary `code` on its path. The VS Code Windows and Linux installations should have installed VS Code on your path. Try uninstalling and reinstalling VS Code. If `code` is still not found, consult the platform specific setup topics for [Windows](/docs/setup/windows.md) and [Linux](/docs/setup/linux.md). + +On macOS, you need to manually run the **Shell Command: Install 'code' command in PATH** command (available through the **Command Palette** `kb(workbench.action.showCommands)`). Consult the [macOS](/docs/setup/mac.md) specific setup topic for details. + +### How do I get access to a command line (terminal) from within VS Code? + +VS Code has an [Integrated Terminal](/docs/editor/integrated-terminal.md) where you can run command line tools from within VS Code. + +### Can I specify the settings location for VS Code in order to have a portable version? + +Not directly through the command line, but VS Code has a [Portable Mode](/docs/editor/portable.md) which lets you keep settings and data in the same location as your installation, for example, on a USB drive. \ No newline at end of file diff --git a/docs/editor/debugging.md b/docs/editor/debugging.md new file mode 100644 index 0000000000000000000000000000000000000000..d809c4d809b1ccff71673c7409ef37bef1213685 --- /dev/null +++ b/docs/editor/debugging.md @@ -0,0 +1,403 @@ +--- +Order: 7 +Area: editor +TOCTitle: Debugging +ContentId: 4E9A74AA-D778-4D1C-B369-83763B3C340F +PageTitle: Debugging in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: One of the great things in Visual Studio Code is debugging support. Set breakpoints, step-in, inspect variables and more. +MetaSocialImage: images/debugging/Debugging.png +--- +# Debugging + +One of the key features of Visual Studio Code is its great debugging support. VS Code's built-in debugger helps accelerate your edit, compile and debug loop. + +![Debugging diagram](images/debugging/debugging_hero.png) + +## Debugger extensions + +VS Code has built-in debugging support for the [Node.js](https://nodejs.org/) runtime and can debug JavaScript, TypeScript, and any other language that gets transpiled to JavaScript. + +For debugging other languages and runtimes (including [PHP](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug), [Ruby](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby), [Go](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go), [C#](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp), [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python), [C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools), [Powershell](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell) and [many others](https://marketplace.visualstudio.com/search?term=debug&target=VSCode&category=Debuggers&sortBy=Relevance)), look for `Debuggers` [extensions](/docs/editor/extension-gallery.md) in our VS Code [Marketplace](https://marketplace.visualstudio.com/vscode/Debuggers) or click on **Install Additional Debuggers** in the top-level Debug menu. + +Below are several popular extensions which include debugging support: + +
+ +> Tip: The extensions shown above are dynamically queried. Click on an extension tile above to read the description and reviews to decide which extension is best for you. + +## Start debugging + +The following documentation is based on the built-in [Node.js](https://nodejs.org/) debugger, but most of the concepts and features are applicable to other debuggers as well. + +It is helpful to first create a sample Node.js application before reading about debugging. You can follow the [Node.js walkthrough](/docs/nodejs/nodejs-tutorial.md) to install Node.js and create a simple "Hello World" JavaScript application (`app.js`). Once you have a simple application all set up, this page will take you through VS Code debugging features. + +## Debug view + +To bring up the Debug view, click on the Debug icon in the **Activity Bar** on the side of VS Code. You can also use the keyboard shortcut `kb(workbench.view.debug)`. + +![Debug icon](images/debugging/debugicon.png) + +The Debug view displays all information related to debugging and has a top bar with debugging commands and configuration settings. + +## Debug menu + +The top-level **Debug** menu has the most common debug commands: + +![Debug menu](images/debugging/debug-menu.png) + +## Launch configurations + +To debug a simple app in VS Code, press `kb(workbench.action.debug.start)` and VS Code will try to debug your currently active file. + +However, for most debugging scenarios, creating a launch configuration file is beneficial because it allows you to configure and save debugging setup details. VS Code keeps debugging configuration information in a `launch.json` file located in a `.vscode` folder in your workspace (project root folder) or in your [user settings](/docs/editor/debugging.md#global-launch-configuration) or [workspace settings](/docs/editor/multi-root-workspaces.md#workspace-launch-configurations). + +To create a `launch.json` file, open your project folder in VS Code (**File** > **Open Folder**) and then click on the Configure gear icon on the Debug view top bar. + +![launch configuration](images/debugging/launch-configuration.png) + +VS Code will try to automatically detect your debug environment, but if this fails, you will have to choose it manually: + +![debug environment selector](images/debugging/debug-environments.png) + +Here is the launch configuration generated for Node.js debugging: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${file}" + } + ] +} +``` + +If you go back to the File Explorer view (`kb(workbench.view.explorer)`), you'll see that VS Code has created a `.vscode` folder and added the `launch.json` file to your workspace. + +![launch.json in Explorer](images/debugging/launch-json-in-explorer.png) + +>**Note**: You can debug a simple application even if you don't have a folder open in VS Code, but it is not possible to manage launch configurations and set up advanced debugging. The VS Code Status Bar is purple if you do not have a folder open. + +Note that the attributes available in launch configurations vary from debugger to debugger. You can use IntelliSense suggestions (`kb(editor.action.triggerSuggest)`) to find out which attributes exist for a specific debugger. Hover help is also available for all attributes. + +Do not assume that an attribute that is available for one debugger automatically works for other debuggers too. If you see green squiggles in your launch configuration, hover over them to learn what the problem is and try to fix them before launching a debug session. + +![launch.json IntelliSense](images/debugging/launch-json-intellisense.png) + +Review all automatically generated values and make sure that they make sense for your project and debugging environment. + +### Launch versus attach configurations + +In VS Code, there are two core debugging modes, **Launch** and **Attach**, which handle two different workflows and segments of developers. Depending on your workflow, it can be confusing to know what type of configuration is appropriate for your project. + +If you come from a browser Developer Tools background, you might not be used to "launching from your tool," since your browser instance is already open. When you open DevTools, you are simply **attaching** DevTools to your open browser tab. On the other hand, if you come from a server or desktop background, it's quite normal to have your editor **launch** your process for you, and your editor automatically attaches its debugger to the newly launched process. + +The best way to explain the difference between **launch** and **attach** is think of a **launch** configuration as a recipe for how to start your app in debug mode **before** VS Code attaches to it, while an **attach** configuration is a recipe for how to connect VS Code's debugger to an app or process that's **already** running. + +VS Code debuggers typically support launching a program in debug mode or attaching to an already running program in debug mode. Depending on the request (`attach` or `launch`), different attributes are required, and VS Code's `launch.json` validation and suggestions should help with that. + +### Add a new configuration + +To add a new configuration to an existing `launch.json`, use one of the following techniques: + +* Use IntelliSense if your cursor is located inside the configurations array. +* Press the **Add Configuration** button to invoke snippet IntelliSense at the start of the array. +* Choose **Add Configuration** option in the Debug menu. + +![launch json suggestions](images/debugging/add-config.gif) + +VS Code also supports compound launch configurations for starting multiple configurations at the same time; for more details, please read this [section](#compound-launch-configurations). + +In order to start a debug session, first select the configuration named **Launch Program** using the **Configuration drop-down** in the Debug view. Once you have your launch configuration set, start your debug session with `kb(workbench.action.debug.start)`. + +Alternatively you can run your configuration through the **Command Palette** (`kb(workbench.action.showCommands)`), by filtering on **Debug: Select and Start Debugging** or typing `'debug '`, and selecting the configuration you want to debug. + +As soon as a debugging session starts, the **DEBUG CONSOLE** panel is displayed and shows debugging output, and the Status Bar changes color (orange for default color themes): + +![debug session](images/debugging/debug-session.png) + +In addition, the **debug status** appears in the Status Bar showing the active debug configuration. By clicking on the debug status, a user can change the active launch configuration and start debugging without needing to open the Debug view. + +![Debug status](images/debugging/debug-status.png) + +## Debug actions + +Once a debug session starts, the **Debug toolbar** will appear on the top of the editor. + +![Debug Actions](images/debugging/toolbar.png) + +* Continue / Pause `kb(workbench.action.debug.continue)` +* Step Over `kb(workbench.action.debug.stepOver)` +* Step Into `kb(workbench.action.debug.stepInto)` +* Step Out `kb(workbench.action.debug.stepOut)` +* Restart `kb(workbench.action.debug.restart)` +* Stop `kb(workbench.action.debug.stop)` + +>**Tip**: Use the setting `debug.toolBarLocation` to control the location of the debug toolbar. It can either be the default `floating`, `docked` to the debug viewlet or `hidden`. A `floating` debug toolbar can be dragged horizontally and also down to the editor area. + +### Run mode + +In addition to debugging a program, VS Code supports **running** the program. The **Debug: Start Without Debugging** action is triggered with `kb(workbench.action.debug.run)` and uses the currently selected launch configuration. Many of the launch configuration attributes are supported in 'Run' mode. VS Code maintains a debug session while the program is running, and pressing the **Stop** button terminates the program. + +>**Tip**: The **Run** action is always available, but not all debugger extensions support 'Run'. In this case, 'Run' will be the same as 'Debug'. + +## Breakpoints + +Breakpoints can be toggled by clicking on the **editor margin**. Finer breakpoint control (enable/disable/reapply) can be done in the Debug view's **BREAKPOINTS** section. + +* Breakpoints in the editor margin are normally shown as red filled circles. +* Disabled breakpoints have a filled gray circle. +* When a debugging session starts, breakpoints that cannot be registered with the debugger change to a gray hollow circle. The same might happen if the source is edited while a debug session without live-edit support is running. + +The **Reapply All Breakpoints** command sets all breakpoints again to their original location. This is helpful if your debug environment is "lazy" and "misplaces" breakpoints in source code that has not yet been executed. + +![Breakpoints](images/debugging/breakpoints.png) + +## Logpoints + +A Logpoint is a variant of a breakpoint that does not "break" into the debugger but instead logs a message to the console. Logpoints are especially useful for injecting logging while debugging production servers that cannot be paused or stopped. + +A Logpoint is represented by a "diamond" shaped icon. Log messages are plain text but can include expressions to be evaluated within curly braces ('{}'). + +![Logpoints](images/debugging/log-points.gif) + +Just like regular breakpoints, Logpoints can be enabled or disabled and can also be controlled by a condition and/or hit count. + +**Note**: Logpoints are currently only supported by VS Code's built-in Node.js debugger, but can be implemented by other debug extensions. The [Python extension](/docs/python/python-tutorial.md), for example, supports Logpoints. + +## Data inspection + +Variables can be inspected in the **VARIABLES** section of the Debug view or by hovering over their source in the editor. Variable values and expression evaluation are relative to the selected stack frame in the **CALL STACK** section. + +![Debug Variables](images/debugging/variables.png) + +Variable values can be modified with the **Set Value** action from the variable's context menu. + +Variables and expressions can also be evaluated and watched in the Debug view's **WATCH** section. + +![Debug Watch](images/debugging/watch.png) + +## Launch.json attributes + +There are many `launch.json` attributes to help support different debuggers and debugging scenarios. As mentioned above, you can use IntelliSense (`kb(editor.action.triggerSuggest)`) to see the list of available attributes once you have specified a value for the `type` attribute. + +![launch json suggestions](images/debugging/launch-json-suggestions.png) + +The following attributes are mandatory for every launch configuration: + +* `type` - the type of debugger to use for this launch configuration. Every installed debug extension introduces a type: `node` for the built-in Node debugger, for example, or `php` and `go` for the PHP and Go extensions. +* `request` - the request type of this launch configuration. Currently, `launch` and `attach` are supported. +* `name` - the reader-friendly name to appear in the Debug launch configuration drop-down. + +Here are some optional attributes available to all launch configurations: + +* `preLaunchTask` - to launch a task before the start of a debug session, set this attribute to the name of a task specified in [tasks.json](/docs/editor/tasks.md) (in the workspace's `.vscode` folder). +* `postDebugTask` - to launch a task at the very end of a debug session, set this attribute to the name of a task specified in [tasks.json](/docs/editor/tasks.md) (in the workspace's `.vscode` folder). +* `internalConsoleOptions` - this attribute controls the visibility of the Debug Console panel during a debugging session. +* `debugServer` - **for debug extension authors only**: this attribute allows you to connect to a specified port instead of launching the debug adapter. + +Many debuggers support some of the following attributes: + +* `program` - executable or file to run when launching the debugger +* `args` - arguments passed to the program to debug +* `env` - environment variables (the value `null` can be used to "undefine" a variable) +* `cwd` - current working directory for finding dependencies and other files +* `port` - port when attaching to a running process +* `stopOnEntry` - break immediately when the program launches +* `console` - what kind of console to use, for example, `internalConsole`, `integratedTerminal`, or `externalTerminal` + +## Variable substitution + +VS Code makes commonly used paths and other values available as variables and supports variable substitution inside strings in `launch.json`. This means that you do not have to use absolute paths in debug configurations. For example, `${workspaceFolder}` gives the root path of a workspace folder, `${file}` the file open in the active editor, and `${env:Name}` the environment variable 'Name'. You can see a full list of predefined variables in the [Variables Reference](/docs/editor/variables-reference.md) or by invoking IntelliSense inside the `launch.json` string attributes. + +```json +{ + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${workspaceFolder}/app.js", + "cwd": "${workspaceFolder}", + "args": [ "${env:USERNAME}" ] +} +``` + +## Platform-specific properties + +`Launch.json` supports defining values (for example, arguments to be passed to the program) that depend on the operating system where the debugger is running. To do so, put a platform-specific literal into the `launch.json` file and specify the corresponding properties inside that literal. + +Below is an example that passes `"args"` to the program differently on Windows: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", + "args": ["myFolder/path/app.js"], + "windows": { + "args": ["myFolder\\path\\app.js"] + } + } + ] +} +``` + +Valid operating properties are `"windows"` for Windows, `"linux"` for Linux and `"osx"` for macOS. Properties defined in an operating system specific scope override properties defined in the global scope. + +In the example below debugging the program always _stops on entry_ except on macOS: +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", + "stopOnEntry": true, + "osx": { + "stopOnEntry": false + } + } + ] +} +``` + +## Global launch configuration + +VS Code supports adding a `"launch"` object inside your User [settings](/docs/getstarted/settings.md). This `"launch"` configuration will then be shared across your workspaces. For example: + +```json +"launch": { + "version": "0.2.0", + "configurations": [{ + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${file}" + }] +} +``` + +>**Tip**: If a workspace contains a `"launch.json"`, the global launch configuration is ignored. + +## Advanced breakpoint topics + +### Conditional breakpoints + +A powerful VS Code debugging feature is the ability to set conditions based on expressions, hit counts, or a combination of both. + +- **Expression condition**: The breakpoint will be hit whenever the expression evaluates to `true`. +- **Hit count**: The 'hit count' controls how many times a breakpoint needs to be hit before it will 'break' execution. Whether a 'hit count' is respected and the exact syntax of the expression vary among debugger extensions. + +You can add a condition and/or hit count when creating the breakpoint (with the **Add Conditional Breakpoint** action) or when modifying an existing one (with the **Edit Breakpoint** action). In both cases, an inline text box with a drop-down menu opens where you can enter expressions: + +![HitCount](images/debugging/hitCount.gif) + +If a debugger does not support conditional breakpoints, the **Add Conditional Breakpoint** action will be missing. + +### Inline breakpoints + +Inline breakpoints will only be hit when the execution reaches the column associated with the inline breakpoint. This is particularly useful when debugging minified code which contains multiple statements on a single line. + +An inline breakpoint can be set using `kb(editor.debug.action.toggleInlineBreakpoint)` or through the context menu during a debug session. Inline breakpoints are shown inline in the editor. + +Inline breakpoints can also have conditions. Editing multiple breakpoints on a line is possible through the context menu in the editor's left margin. + +### Function breakpoints + +Instead of placing breakpoints directly in source code, a debugger can support creating breakpoints by specifying a function name. This is useful in situations where source is not available but a function name is known. + +A function breakpoint is created by pressing the **+** button in the **BREAKPOINTS** section header and entering the function name. Function breakpoints are shown with a red triangle in the **BREAKPOINTS** section. + +## Debug Console REPL + +Expressions can be evaluated with the **Debug Console** REPL ([Read-Eval-Print Loop](https://en.wikipedia.org/wiki/Read–eval–print_loop)) feature. To open the Debug Console, use the **Debug Console** action at the top of the Debug pane or use the **View: Debug Console** command (`kb(workbench.debug.action.toggleRepl)`). Expressions are evaluated after you press `kbstyle(Enter)` and the Debug Console REPL shows suggestions as you type. If you need to enter multiple lines, use `kbstyle(Shift+Enter)` between the lines and then send all lines for evaluation with `kbstyle(Enter)`. + +![Debug Console](images/debugging/debugconsole.png) + +**Note**: You must be in a running debug session to use the Debug Console REPL. + +## Multi-target debugging + +For complex scenarios involving more than one process (for example, a client and a server), VS Code supports multi-target debugging. + +Using multi-target debugging is simple: after you've started a first debug session, you can just launch another session. As soon as a second session is up and running, the VS Code UI switches to _multi-target mode_: + +- The individual sessions now show up as top-level elements in the **CALL STACK** view.
![Callstack View](images/debugging/debug-callstack.png) +- The debug toolbar shows the currently **active session** (and all other sessions are available in a drop-down menu).
![Debug Actions Widget](images/debugging/debug-actions-widget.png) +- Debug actions (for example, all actions in the debug toolbar) are performed on the active session. The active session can be changed either by using the drop-down menu in the debug toolbar or by selecting a different element in the **CALL STACK** view. + +### Compound launch configurations + +An alternative way to start multiple debug sessions is by using a **compound** launch configuration. A compound launch configuration lists the names of two or more launch configurations that should be launched in parallel. Compound launch configurations are displayed in the launch configuration drop-down menu. + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Server", + "program": "${workspaceFolder}/server.js", + "cwd": "${workspaceFolder}" + }, + { + "type": "node", + "request": "launch", + "name": "Client", + "program": "${workspaceFolder}/client.js", + "cwd": "${workspaceFolder}" + } + ], + "compounds": [ + { + "name": "Server/Client", + "configurations": ["Server", "Client"] + } + ] +} +``` + +## Remote debugging + +VS Code does not itself support remote debugging: this is a feature of the debug extension you are using, and you should consult the extension's page in the [Marketplace](https://marketplace.visualstudio.com/search?target=VSCode&category=Debuggers&sortBy=Downloads) for support and details. + +There is, however, one exception: the Node.js debugger included in VS Code supports remote debugging. See the [Node.js Debugging](/docs/nodejs/nodejs-debugging.md#remote-debugging) topic to learn how to configure this. + +## Next steps + +To learn about VS Code's Node.js debugging support, take a look at: + +* [Node.js](/docs/nodejs/nodejs-debugging.md) - Describes the Node.js debugger, which is included in VS Code. + +To see tutorials on the basics of Node.js debugging, check out these videos: + +* [Intro Video - Debugging](/docs/introvideos/debugging.md) - Showcases the basics of debugging. +* [Getting started with Node.js debugging](https://www.youtube.com/watch?v=2oFKNL7vYV8) - Shows how to attach a debugger to a running Node.js process. + +To learn about VS Code's task running support, go to: + +* [Tasks](/docs/editor/tasks.md) - Describes how to run tasks with Gulp, Grunt and Jake, and how to show errors and warnings. + +To write your own debugger extension, visit: + +* [Debugger Extension](/api/extension-guides/debugger-extension.md) - Uses a mock sample to illustrate the steps required to create a VS Code debug extension. + +## Common questions + +### What are the supported debugging scenarios? + +Debugging of Node.js-based applications is supported on Linux, macOS, and Windows out of the box with VS Code. Many other scenarios are supported by [VS Code extensions](https://marketplace.visualstudio.com/vscode/Debuggers?sortBy=Downloads) available in the Marketplace. + +### I do not see any launch configurations in the debug view drop-down. What is wrong? + +The most common problem is that you did not set up `launch.json` or there is a syntax error in that file. Alternatively, you might need to open a folder, since no-folder debugging does not support launch configurations. \ No newline at end of file diff --git a/docs/editor/editingevolved.md b/docs/editor/editingevolved.md new file mode 100644 index 0000000000000000000000000000000000000000..e7d2625c08957f0eb9359aa3d708fc76a2aa4759 --- /dev/null +++ b/docs/editor/editingevolved.md @@ -0,0 +1,115 @@ +--- +Order: 5 +Area: editor +TOCTitle: Code Navigation +ContentId: 8966BBFD-C66D-4283-9DCA-8CAC0179886E +PageTitle: Code Navigation in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code is a first class editor - but it's also so much more with features such as IntelliSense and smart code navigation. +--- +# Code Navigation + +Visual Studio Code has a high productivity code editor which, when combined with programming language services, gives you the power of an IDE and the speed of a text editor. In this topic, we'll first describe VS Code's language intelligence features (suggestions, parameter hints, smart code navigation) and then show the power of the core text editor. + +## Quick file navigation + +>**Tip:** You can open any file by its name when you type `kb(workbench.action.quickOpen)` (**Quick Open**). + +The Explorer is great for navigating between files when you are exploring a project. However, when you are working on a task, you will find yourself quickly jumping between the same set of files. VS Code provides two powerful commands to navigate in and across files with easy-to-use key bindings. + +Hold `kbstyle(Ctrl)` and press `kbstyle(Tab)` to view a list of all files open in an editor group. To open one of these files, use `kbstyle(Tab)` again to pick the file you want to navigate to, then release `kbstyle(Ctrl)` to open it. + +![Quick Navigation](images/editingevolved/quicknav.png) + +Alternatively, you can use `kb(workbench.action.navigateBack)` and `kb(workbench.action.navigateForward)` to navigate between files and edit locations. If you are jumping around between different lines of the same file, these shortcuts allow you to navigate between those locations easily. + +## Go to Definition + +If a [language](/docs/languages/overview.md) supports it, you can go to the definition of a symbol by pressing `kb(editor.action.revealDefinition)`. + +If you press `kbstyle(Ctrl)` and hover over a symbol, a preview of the declaration will appear: + +![Ctrl Hover](images/editingevolved/ctrlhover.png) + +> **Tip:** You can jump to the definition with `kbstyle(Ctrl+Click)` or open the definition to the side with `kbstyle(Ctrl+Alt+Click)`. + +## Go to Type Definition + +Some [languages](/docs/languages/overview.md) also support jumping to the type definition of a symbol by running the **Go to Type Definition** command from either the editor context menu or the **Command Palette**. This will take you to the definition of the type of a symbol. The command `editor.action.goToTypeDefinition` is not bound to a keyboard shortcut by default but you can add your own custom [keybinding](/docs/getstarted/keybindings.md). + +## Go to Implementation + +[Languages](/docs/languages/overview.md) can also support jumping to the implementation of a symbol by pressing `kb(editor.action.goToImplementation)`. For an interface, this shows all the implementors of that interface and for abstract methods, this shows all concrete implementations of that method. + +## Go to Symbol + +You can navigate symbols inside a file with `kb(workbench.action.gotoSymbol)`. By typing `kbstyle(:)` the symbols will be grouped by category. Press `kbstyle(Up)` or `kbstyle(Down)` and navigate to the place you want. + +![Go to Symbol](images/editingevolved/gotosymbol.png) + +## Open symbol by name + +Some languages support jumping to a symbol across files with `kb(workbench.action.showAllSymbols)`. Type the first letter of a type you want to navigate to, regardless of which file contains it, and press `kbstyle(Enter)`. + +![Open symbol by name](images/editingevolved/symbol.png) + +## Peek + +We think there's nothing worse than a big context switch when all you want is to quickly check something. That's why we support peeked editors. When you execute a **Peek References** search (via `kb(editor.action.referenceSearch.trigger)`), or a **Peek Definition** (via `kb(editor.action.peekDefinition)`), we embed the result inline: + +![Peek References](images/editingevolved/references.png) + +You can navigate between different references in the peeked editor and make quick edits right there. Clicking on the peeked editor filename or double-clicking in the result list will open the reference in the outer editor. + +> **Tip:** Additionally, the peek window is closed if you press `kbstyle(Escape)` or double-click in the peek editor region. You can disable this behavior with the `editor.stablePeek` [setting](/docs/getstarted/settings.md). + +## Bracket matching + +Matching brackets will be highlighted as soon as the cursor is near one of them. + +![Bracket Matching](images/editingevolved/brackets.png) + +> **Tip:** You can jump to the matching bracket with `kb(editor.action.jumpToBracket)` + +## Reference information + +Some languages like C# support inline reference information, that is updated live. This allows you to quickly analyze the impact of your edit or the popularity of your specific method or property throughout your project: + +![Reference information](images/editingevolved/referenceinfo.png) + +> **Tip:** Directly invoke the **Peek References** action by clicking on these annotations. + +> **Tip:** Reference information shown in CodeLens can be turned on or off through the `editor.codeLens` setting. + +## Rename symbol + +Some languages support rename symbol across files. Press `kb(editor.action.rename)` and then type the new desired name and press `kbstyle(Enter)`. All usages of the symbol will be renamed, across files. + +![Rename](images/editingevolved/rename.png) + +## Errors & warnings + +Warnings or Errors can be generated either via [configured tasks](/docs/editor/tasks.md), by rich language services, or by linters, that constantly analyze your code in the background. Since we love bug-free code, warnings and errors show up in multiple places: + +* In the Status Bar, there is a summary of all errors and warnings counts. +* You can click on the summary or press `kb(workbench.actions.view.problems)` to display the **PROBLEMS** panel with a list of all current errors. +* If you open a file that has errors or warnings, they will be rendered inline with the text and in the overview ruler. + +![errors in problems panel](images/editingevolved/errors.png) + +> **Tip:** To loop through errors or warnings in the current file, you can press `kb(editor.action.marker.nextInFiles)` or `kb(editor.action.marker.prevInFiles)` which will show an inline zone detailing the problem and possible Code Actions (if available): + +![Errors and Warnings Inline](images/editingevolved/errorsinline.png) + +## Code Action + +Warnings and Errors can provide Code Actions (also known as Quick Fixes) to help fix issues. These will be displayed in the editor in the left margin as a lightbulb. Clicking on the lightbulb will either display the Code Action options or perform the action. + +## Next steps + +Now that you know how the editor works, time to try a few other things... + +* [Intro Video - Code Editing](/docs/introvideos/codeediting.md) - Watch an introductory video on code editing features. +* [User Interface](/docs/getstarted/userinterface.md) - In case you missed a basic orientation around VS Code. +* [Key Bindings](/docs/getstarted/keybindings.md) - Learn how to modify key bindings to your preference. +* [Debugging](/docs/editor/debugging.md) - This is where VS Code really shines. diff --git a/docs/editor/emmet.md b/docs/editor/emmet.md new file mode 100644 index 0000000000000000000000000000000000000000..39e5f038e8b67cf3fbd10ee1af6d3e912e3cb26a --- /dev/null +++ b/docs/editor/emmet.md @@ -0,0 +1,393 @@ +--- +Order: 13 +Area: editor +TOCTitle: Emmet +ContentId: baf4717c-ea52-486e-9ea3-7bf1c4134dad +PageTitle: Emmet in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Using Emmet abbreviations inside Visual Studio Code. +--- +# Emmet in Visual Studio Code + +Emmet support is built right into Visual Studio Code, **no extension is required**. [Emmet 2.0](https://code.visualstudio.com/blogs/2017/08/07/emmet-2.0) has support for the majority of the [Emmet Actions](https://docs.emmet.io/actions/) including expanding [Emmet abbreviations and snippets](https://docs.emmet.io/cheat-sheet/). + +## How to expand Emmet abbreviations and snippets + +Emmet abbreviation and snippet expansions are enabled by default in `html`, `haml`, `jade`, `slim`, `jsx`, `xml`, `xsl`, `css`, `scss`, `sass`, `less` and `stylus` files. As well as any language that inherits from any of the above like `handlebars` and `php`. + +![Emmet in suggestion/auto-completion list](images/emmet/emmet.gif) + +When you start typing an Emmet abbreviation, you will see the abbreviation displayed in the suggestion list. If you have the suggestion documentation fly-out open, you will see a preview of the expansion as you type. If you are in a stylesheet file, the expanded abbreviation shows up in the suggestion list sorted among the other CSS suggestions. + +### Using Tab for Emmet expansions + +If you want to use the `kbstyle(Tab)` key for expanding the Emmet abbreviations, add the following setting: + +```json +"emmet.triggerExpansionOnTab": true +``` + +This setting allows using the `kbstyle(Tab)` key for indentation when text is not an Emmet abbreviation. + +### Emmet when quickSuggestions are disabled + +If you have disabled the `editor.quickSuggestions` [setting](/docs/getstarted/settings.md), you won't see suggestions as you type. You can still trigger suggestions manually by pressing `kb(editor.action.triggerSuggest)` and see the preview. + +### Disable Emmet in suggestions + +If you don't want to see Emmet abbreviations in suggestions at all, then use the following setting: + +```json +"emmet.showExpandedAbbreviation": "never" +``` + +You can still use the command **Emmet: Expand Abbreviation** to expand your abbreviations. You can also bind any keyboard shortcut to the command id `editor.emmet.action.expandAbbreviation` as well. + +### Emmet suggestion ordering + +To ensure Emmet suggestions are always on top in the suggestion list, add the following settings: + +```json +"emmet.showSuggestionsAsSnippets": true, +"editor.snippetSuggestions": "top" +``` + +## Emmet abbreviations in other file types + +To enable the Emmet abbreviation expansion in file types where it is not available by default, use the `emmet.includeLanguages` setting. Make sure to use [language identifiers](/docs/languages/identifiers.md) for both sides of the mapping. + +For example: + +```json +"emmet.includeLanguages": { + "javascript": "javascriptreact", + "vue-html": "html", + "razor": "html", + "plaintext": "jade" +} +``` + +Emmet has no knowledge of these new languages, and so you might feel Emmet suggestions showing up in non HTML/CSS context. To avoid this, you can use the following setting. + +```json +"emmet.showExpandedAbbreviation": "inMarkupAndStylesheetFilesOnly" +``` + +> **Note:** If you used `emmet.syntaxProfiles` previously to map new file types, from VS Code 1.15 onwards you should use the setting `emmet.includeLanguages` instead. `emmet.syntaxProfiles` is meant for [customizing the final output](https://docs.emmet.io/customization/syntax-profiles) only. + +## Emmet with multi-cursors + +You can use most of the Emmet actions with multi-cursors as well: + +![Emmet with multi cursors](images/emmet/emmet-multi-cursor.gif) + +## Include vendor prefixes + +Prefix your CSS abbreviations with `-` to get all applicable vendor prefixes included in the expanded abbreviation. + +![Vendor prefix in emmet](images/emmet/emmet-vendor-prefix.gif) + +Below are a few examples of how you can control which vendors get applied to which CSS property by updating the `emmet.preferences` setting: + +```json +{ + "emmet.preferences": { + "css.webkitProperties": "border-right,animation", + "css.mozProperties": "", + "css.oProperties": null, + "css.msProperties": null + } +} +``` + +- Setting the preference to a comma separated list of CSS properties will ensure that the corresponding prefix gets added only to these CSS properties. +- Setting the preference to an empty string will ensure that the corresponding prefix doesn't get added to any CSS property. +- Setting the preference to null will ensure that the default CSS properties for each vendor as documented in [Emmet Preferences](https://docs.emmet.io/customization/preferences/) get used. + +## Using filters + +Filters are special post-processors that modify the expanded abbreviation before it is output to the editor. There are 2 ways to use filters; either globally through the `emmet.syntaxProfiles` setting or directly in the current abbreviation. + +Below is an example of the first approach using the `emmet.syntaxProfiles` setting to apply the `bem` filter for all the abbreviations in HTML files: + +```json +"emmet.syntaxProfiles": { + "html": { + "filters": "bem" + } +} + +``` + +To provide a filter for just the current abbreviation, append the filter to your abbreviation. For example, `div#page|c` will apply the `comment` filter to the `div#page` abbreviation. + +### BEM filter (bem) + +If you use the [Block Element Modifier](http://getbem.com/) (BEM) way of writing HTML, then `bem` filters are very handy for you to use. To learn more about how to use `bem` filters, read [BEM filter in Emmet](https://docs.emmet.io/filters/bem/). + +You can customize this filter by using the `bem.elementSeparator` and `bem.modifierSeparator` preferences as documented in [Emmet Preferences](https://docs.emmet.io/customization/preferences/). + +### Comment filter (c) + +This filter adds comments around important tags. By default, "important tags" are those tags with id and/or class attribute. + +For example `div>div#page>p.title+p|c` will be expanded to: + +```xml +
+
+

+ +

+
+ +
+``` + +You can customize this filter by using the `filter.commentTrigger`, `filter.commentAfter` and `filter.commentBefore` preferences as documented in [Emmet Preferences](https://docs.emmet.io/customization/preferences/). + +The format for the `filter.commentAfter` preference is different in VS Code Emmet 2.0. + +For example, instead of: + +```json +"emmet.preferences": { + "filter.commentAfter": "\n" +} +``` + +in VS Code, you would use a simpler: + +```json +"emmet.preferences": { + "filter.commentAfter": "\n" +} +``` + +### Trim filter (t) + +This filter is applicable only when providing abbreviations for the **Emmet: Wrap Individual Lines with Abbreviation** command. It [removes line markers](https://docs.emmet.io/actions/wrap-with-abbreviation/#removing-list-markers) from wrapped lines. + +## Using custom Emmet snippets + +Custom Emmet snippets need to be defined in a json file named `snippets.json`. The `emmet.extensionsPath` setting should have the path to the directory containing this file. + +Below is an example for the contents of this `snippets.json` file. + +```json +{ + "html": { + "snippets": { + "ull": "ul>li[id=${1} class=${2}]*2{ Will work with html, jade, haml and slim }", + "oll": "
  1. Will only work in html
", + "ran": "{ Wrap plain text in curly braces }" + } + }, + "css": { + "snippets": { + "cb": "color: black", + "bsd": "border: 1px solid ${1:red}", + "ls": "list-style: ${1}" + } + } +} +``` + +Authoring of Custom Snippets in Emmet 2.0 via the `snippets.json` file differs from the old way of doing the same in a few ways: + +Topic | Old Emmet | Emmet 2.0 +------ | -------- | --------- +Snippets vs Abbreviations | Supports both in 2 separate properties called `snippets` and `abbreviations` | The 2 have been combined into a single property called snippets. See default [HTML snippets](https://github.com/emmetio/snippets/blob/master/html.json) and [CSS snippets](https://github.com/emmetio/snippets/blob/master/css.json) +CSS snippet names | Can contain `:` | Do not use `:` when defining snippet names. It is used to separate property name and value when Emmet tries to fuzzy match the given abbreviation to one of the snippets. +CSS snippet values | Can end with `;` | Do not add `;` at end of snippet value. Emmet will add the trailing `;` based on the file type (css/less/scss vs sass/stylus) or the emmet preference set for `css.propertyEnd`, `sass.propertyEnd`, `stylus.propertyEnd` +Cursor location | `${cursor}` or `|` can be used | Use only textmate syntax like `${1}` for tab stops and cursor locations + +### HTML Emmet snippets + +HTML custom snippets are applicable to all other markup flavors like `haml` or `jade`. When snippet value is an abbreviation and not actual HTML, the appropriate transformations can be applied to get the right output as per the language type. + +For example, for an unordered list with a list item, if your snippet value is `ul>li`, you can use the same snippet in `html`, `haml`, `jade` or `slim`, but if your snippet value is `
`, then it will work only in `html` files. + +If you want a snippet for plain text, then surround the text with the `{}`. + +### CSS Emmet snippets + +Values for CSS Emmet snippets should be a complete property name and value pair. + +CSS custom snippets are applicable to all other stylesheet flavors like `scss`, `less` or `sass`. Therefore, don't include a trailing `;` at the end of the snippet value. Emmet will add it as needed based on the whether the language requires it. + +Do not use `:` in the snippet name. `:` is used to separate property name and value when Emmet tries to fuzzy match the abbreviation to one of the snippets. + +> Note: After making changes to the `snippets.json` file, remember to reload VS Code for it to take effect. + +### Tab stops and cursors in custom snippets + +The syntax for tab stops in custom Emmet snippets follows the [Textmate snippets syntax](https://manual.macromates.com/en/snippets). + +- Use `${1}`, `${2}` for tab stops and `${1:placeholder}` for tab stops with placeholders. +- Previously, `|` or `${cursor}` was used to denote the cursor location in the custom Emmet snippet. This is no longer supported. Use `${1}` instead. + +## Emmet configuration + +Below are Emmet [settings](/docs/getstarted/settings.md) that you can use to customize your Emmet experience in VS Code. + +* `emmet.includeLanguages` + + Use this setting to add mapping between the language of your choice and one of the Emmet supported languages to enable Emmet in the former using the syntax of the latter. + Make sure to use language ids for both sides of the mapping. + + For example: + ```json + "emmet.includeLanguages": { + "javascript": "javascriptreact", + "vue-html": "html", + "plaintext": "jade" + } + ``` + +* `emmet.excludeLanguages` + + If there is a language where you do not want to see Emmet expansions, add it in this setting which takes an array of language id strings. + +* `emmet.syntaxProfiles` + + See [Emmet Customization of output profile](https://docs.emmet.io/customization/syntax-profiles/#create-your-own-profile) to learn how you can customize the output of your HTML abbreviations. + + For example: + ```json + "emmet.syntaxProfiles": { + "html": { + "attr_quotes": "single" + }, + "jsx": { + "self_closing_tag": true + } + } + ``` + +* `emmet.variables` + + Customize variables used by Emmet snippets. + + For example: + ```json + "emmet.variables": { + "lang": "de", + "charset": "UTF-16" + } + ``` + +* `emmet.showExpandedAbbreviation` + + Controls the Emmet suggestions that show up in the suggestion/completion list. + + Setting Value | Description + ----------- | ------- + `never` | Never show Emmet abbreviations in the suggestion list for any language. + `inMarkupAndStylesheetFilesOnly` | Show Emmet suggestions only for languages that are purely markup and stylesheet based ('html', 'pug', 'slim', 'haml', 'xml', 'xsl', 'css', 'scss', 'sass', 'less', 'stylus'). + `always` | Show Emmet suggestions in all Emmet supported modes as well as the languages that have a mapping in the `emmet.includeLanguages` setting. + + **Note:** In the `always` mode, the new Emmet implementation is not context aware. For example, if you are editing a JavaScript React file, you will get Emmet suggestions not only when writing markup but also while writing JavaScript. + +* `emmet.showAbbreviationSuggestions` + + Shows possible emmet abbreviations as suggestions. It is `true` by default. + + For example, when you type `li`, you get suggestions for all emmet snippets starting with `li` like `link`, `link:css` , `link:favicon` etc. + This is helpful in learning Emmet snippets that you never knew existed unless you knew the [Emmet cheatsheet](https://docs.emmet.io/cheat-sheet/) by heart. + + Not applicable in stylesheets or when `emmet.showExpandedAbbreviation` is set to `never`. + +* `emmet.extensionsPath` + + Provide the location of the directory that houses the `snippets.json` file which in turn has your custom snippets. + +* `emmet.triggerExpansionOnTab` + + Set this to true to enable expanding Emmet abbreviations with `kbstyle(Tab)` key. We use this setting to provide the appropriate fallback to provide indentation when there is no abbreviation to expand. + +* `emmet.showSuggestionsAsSnippets` + + If set to `true`, then Emmet suggestions will be grouped along with other snippets allowing you to order them as per `editor.snippetSuggestions` setting. Set this to `true` and `editor.snippetSuggestions` to `top`, to ensure that Emmet suggestions always show up on top among other suggestions. + +* `emmet.preferences` + + You can use this setting to customize Emmet as documented in [Emmet Preferences](https://docs.emmet.io/customization/preferences/). The below customizations are currently supported: + - `css.propertyEnd` + - `css.valueSeparator` + - `sass.propertyEnd` + - `sass.valueSeparator` + - `stylus.propertyEnd` + - `stylus.valueSeparator` + - `css.unitAliases` + - `css.intUnit` + - `css.floatUnit` + - `bem.elementSeparator` + - `bem.modifierSeparator` + - `filter.commentBefore` + - `filter.commentTrigger` + - `filter.commentAfter` + - `format.noIndentTags` + - `format.forceIndentationForTags` + - `profile.allowCompactBoolean`, + - `css.webkitProperties` + - `css.mozProperties` + - `css.msProperties` + - `css.oProperties` + - `css.fuzzySearchMinScore` + + The format for the `filter.commentAfter` preference is different and simpler in Emmet 2.0. + + For example, instead of the older format + + ```json + "emmet.preferences": { + "filter.commentAfter": "\n" + } + ``` + + you would use + + ```json + "emmet.preferences": { + "filter.commentAfter": "\n" + } + ``` + + If you want support for any of the other preferences as documented in [Emmet Preferences](https://docs.emmet.io/customization/preferences/), please log a [feature request](https://github.com/Microsoft/vscode/issues/new). + +## Next steps + +Emmet is just one of the great web developer features in VS Code. Read on to find out about: + +* [HTML](/docs/languages/html.md) - VS Code supports HTML with IntelliSense, closing tags, and formatting. +* [CSS](/docs/languages/css.md) - We offer rich support for CSS, SCSS and Less. + +## Common questions + +### Custom tags do not get expanded in the suggestion list + +Custom tags when used in an expression like `MyTag>YourTag` or `MyTag.someclass` do show up in the suggestion list. But when these are used on their own like `MyTag`, they do not appear in the suggestion list. This is designed so to avoid noise in the suggestion list as every word is a potential custom tag. + +Add the following setting to enable expanding of Emmet abbreviations using tab which will expand custom tags in all cases. + +```json +"emmet.triggerExpansionOnTab": true +``` + +### My HTML snippets ending with `+` does not work? + +HTML snippets ending with `+` like `select+` and `ul+` from the [Emmet cheatsheet](https://docs.emmet.io/cheat-sheet/) are not supported. This is a known issue in Emmet 2.0 [Issue: emmetio/html-matcher#1](https://github.com/emmetio/html-matcher/issues/1). Workaround is to create your own [custom Emmet snippets](/docs/editor/emmet.md#using-custom-emmet-snippets) for such scenarios. + +### Where can I set all the preferences as documented in [Emmet preferences](https://docs.emmet.io/customization/preferences/) + +You can set the preferences using the setting `emmet.preferences`. Only a subset of the preferences that are documented in [Emmet preferences](https://docs.emmet.io/customization/preferences/) can be customized. Please read the preferences section under [Emmet configuration](/docs/editor/emmet.md#emmet-configuration). + +### Any tips and tricks? + +Of course! + +- In CSS abbreviations, when you use `:`, the left part is used to fuzzy match with the CSS property name and the right part is used to match with CSS property value. Take full advantage of this by using abbreviations like `pos:f`, `trf:rx`, `fw:b`, etc. +- Use the new command **Emmet: Wrap Individual Lines with Abbreviation** instead of **Emmet: Wrap with Abbreviation** when you want each selected line to be wrapped by a repeater in the given abbreviation. For example, use `ul>li*` to wrap selected lines in an unordered list with each line as a list item. +- Explore all other Emmet features as documented in [Emmet Actions](https://docs.emmet.io/actions/). +- Don't hesitate to create your own [custom Emmet snippets](/docs/editor/emmet.md#using-custom-emmet-snippets). diff --git a/docs/editor/extension-gallery.md b/docs/editor/extension-gallery.md new file mode 100644 index 0000000000000000000000000000000000000000..88006270b033747233e0ef3123bb194b97bf6860 --- /dev/null +++ b/docs/editor/extension-gallery.md @@ -0,0 +1,291 @@ +--- +Order: 3 +Area: editor +TOCTitle: Extension Marketplace +ContentId: 319916C4-93F2-471F-B448-FD416736C40C +PageTitle: Managing Extensions in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Discover, add, update, disable and uninstall Visual Studio Code extensions (plug-ins) through the Extension Marketplace. +--- +# Extension Marketplace + +**Increase the power of Visual Studio Code through Extensions** + +The features that Visual Studio Code includes out-of-the-box are just the start. VS Code extensions let you add languages, debuggers, and tools to your installation to support your development workflow. VS Code's rich extensibility model lets extension authors plug directly into the VS Code UI and contribute functionality through the same APIs used by VS Code. This topic explains how to find, install, and manage VS Code extensions. + +## Browse for extensions + +You can browse and install extensions from within VS Code. Bring up the Extensions view by clicking on the Extensions icon in the **Activity Bar** on the side of VS Code or the **View: Extensions** command (`kb(workbench.view.extensions)`). + +![Extensions view icon](images/extension-gallery/extensions-view-icon.png) + +This will show you a list of the most popular VS Code extensions on the [VS Code Marketplace](https://marketplace.visualstudio.com/VSCode). + +![popular extensions](images/extension-gallery/extensions-popular.png) + +Each extension in the list includes a brief description, the publisher, the download count and a five star rating. You can click on the extension item to display the extension's details page where you can learn more. + +> **Note:** If your computer's Internet access goes through a proxy server, you will need to configure the proxy server. See [Proxy server support](/docs/setup/network.md#proxy-server-support) for details. + +### Install an extension + +Click the **Install** button and after a successful install, you'll see a **Reload** button. Clicking on this will restart VS Code to enable the new extension. + +### Extension details + +On the extension details page, you can read the extension's README as well as review the extension's: + +* **Contributions** - The extension's additions to VS Code such as settings, commands and keyboard shortcuts, language grammars, debugger, etc. +* **Changelog** - The extension repository CHANGELOG if available. +* **Dependencies** - Lists if the extension depends on any other extensions. + +![extension contributions](images/extension-gallery/extension-contributions.png) + +If an extension is an Extension Pack, the **Dependencies** section will display which extensions will be installed when you install the pack. [Extension Packs](/api/references/extension-manifest.md#extension-packs) bundle separate extensions together so they can be easily installed at one time. + +![extension dependencies](images/extension-gallery/extension-dependencies.png) + +### Extensions view commands + +You can run various Extensions view commands by clicking on the Extensions view's `...` **More Actions** button. + +![more button](images/extension-gallery/more-button.png) + +There are commands to show: + +* The list of currently installed extensions +* The list of outdated extensions that can be updated +* The list of currently enabled/disabled extensions +* The list of recommended extensions based on your workspace +* The list of globally popular extensions + +You can sort the extension list by **Install Count** or **Rating** in either ascending or descending order. You can learn more about extension search filters [below](#extensions-view-filters). + +![more drop-down](images/extension-gallery/more-dropdown.png) + +### Search for an extension + +You can clear the Search box at the top of the Extensions view and type in the name of the extension, tool or programming language you're looking for. + +For example, typing 'python' will bring up a list of Python language extensions: + +![python extensions](images/extension-gallery/extensions-python.png) + +If you know the exact identifier for an extension you're looking for, you can use the `@id:` prefix, for example `@id:octref.vetur`. Additionally, to filter or sort results, you can use the [filter](#extensions-view-filters) and [sort](#sorting) commands, detailed below. + +## Manage extensions + +VS Code makes it very easy to manage your extensions. You can install, disable, update, and uninstall extensions through the Extensions view, the **Command Palette** (commands have the **Extensions:** prefix) or command line switches. + +### List installed extensions + +By default, the Extensions view will show the extensions you currently have enabled, all extensions that are recommended for you, and a collapsed view of all extensions you have disabled. You can use the **Show Installed Extensions** command, available in the **Command Palette** (`kb(workbench.action.showCommands)`) or the **More Actions** (`...`) drop-down menu, to clear any text in the search box and show the list of all installed extensions, which includes those that have been disabled. + +### Uninstall an extension + +To uninstall an extension, click the gear button at the right of an extension entry and then choose **Uninstall** from the drop-down menu. This will uninstall the extension and prompt you to reload VS Code. + +![uninstall an extension](images/extension-gallery/uninstall-extension.png) + +### Disable an extension + +If you don't want to permanently remove an extension, you can instead temporarily disable the extension by clicking the gear button at the right of an extension entry. You can disable an extension globally or just for your current Workspace. You will be prompted to reload VS Code after you disable an extension. + +If you want to quickly disable all installed extensions, there is a **Disable All Installed Extensions** command in the **Command Palette** and **More Actions** (`...`) drop-down menu. + +Extensions remain disabled for all VS Code sessions until you re-enable them. + +### Enable an extension + +Similarly if you have disabled an extension (it will be in the **Disabled** section of the list and marked ***Disabled***), you can re-enable it with the **Enable** or **Enable (Workspace)** commands in the drop-down menu. + +![enable extension](images/extension-gallery/enable-extension.png) + +There is also an **Enable All Extensions** command in the **More Actions** (`...`) drop-down menu. + +### Extension auto-update + +VS Code checks for extension updates and installs them automatically. After an update, you will be prompted to reload VS Code. If you'd rather update your extensions manually, you can disable auto-update with the **Disable Auto Updating Extensions** command which sets the `extensions.autoUpdate` [setting](/docs/getstarted/settings.md) to `false`. If you don't want VS Code to even check for updates, you can set the `extensions.autoCheckUpdates` setting to false. + +### Update an extension manually + +If you have extensions auto-update disabled, you can quickly look for extension updates by using the **Show Outdated Extensions** command which uses the `@outdated` filter. This will display any available updates for your currently installed extensions. Click the **Update** button for the outdated extension and the update will be installed and you'll be prompted to reload VS Code. You can also update all your outdated extensions at one time with the **Update All Extensions** command. If you also have automatic checking for updates disabled, you can use the **Check for Extension Updates** command to check which of your extensions can be updated. + +## Recommended extensions + +You can see a list of recommended extensions using **Show Recommended Extensions**, which sets the `@recommended` [filter](#extensions-view-filters). Extension recommendations can either be : + +* **Workspace Recommendations** - Recommended by other users of your current workspace. +* **Other Recommendations** - Recommended based on recently opened files. + +See the section below to learn how to [contribute](#workspace-recommended-extensions) recommendations for other users in your project. + +### Ignoring recommendations + +To dismiss a recommendation, click on the extension item to open the Details pane and then press the **Ignore Recommendation** button. Ignored recommendations will no longer be recommended to you. + +![Ignore extension recommendation](images/extension-gallery/ignore-recommendation.png) + +## Configuring extensions + +VS Code extensions may have very different configurations and requirements. Some extensions contribute [settings](/docs/getstarted/settings.md) to VS Code, which can be modified in the Settings editor. Other extensions may have their own configuration files. Extensions may also require installation and setup of additional components like compilers, debuggers, and command line tools. Consult the extension's README (visible in the Extensions view details page) or go to the extension page on the [VS Code Marketplace](https://marketplace.visualstudio.com/VSCode) (click on the extension name in the details page). Many extensions are open source and have a link to their repository on their Marketplace page. + +## Command line extension management + +To make it easier to automate and configure VS Code, it is possible to list, install, and uninstall extensions from the [command line](/docs/editor/command-line.md). When identifying an extension, provide the full name of the form `publisher.extension`, for example `ms-python.python`. + +Example: + +``` +code --extensions-dir + Set the root path for extensions. +code --list-extensions + List the installed extensions. +code --show-versions + Show versions of installed extensions, when using --list-extension. +code --install-extension ( | ) + Installs an extension. +code --uninstall-extension ( | ) + Uninstalls an extension. +code --enable-proposed-api () + Enables proposed API features for extensions. Can receive one or more extension IDs to enable individually. +``` + +You can see the extension id on the extension details page next to the extension name. + +![extension identifier](images/extension-gallery/extension-identifier.png) + +## Extensions view filters + +The Extensions view search box supports filters to help you find and manage extensions. You may have seen filters such as `@installed` and `@recommended` if you used the commands **Show Installed Extensions** and **Show Recommended Extensions**. There are also filters to let you sort by popularity and ratings and search by category (for example 'Linters') and tags (for example 'node'). You can see a complete listing of all filter and sort commands by typing `@` in the extensions search box and navigating through the suggestions: + +![intellisense on extension search filters](images/extension-gallery/extension-search-filters.png) + +Here are the Extensions view filters: + +* `@builtin` - Show extensions that come with VS Code. Grouped by type (Programming Languages, Themes, etc.). +* `@disabled` - Show disabled installed extensions. +* `@installed` - Show installed extensions. +* `@outdated` - Show outdated installed extensions. A newer version is available on the Marketplace. +* `@enabled` - Show enabled installed extensions. Extensions can be individually enabled/disabled. +* `@recommended` - Show recommended extensions. Grouped as Workspace specific or general use. +* `@category` - Show extensions belonging to specified category. Below are a few of supported categories. For a complete list, type `@category` and follow the options in the suggestion list: + * `@category:themes` + * `@category:formatters` + * `@category:linters` + * `@category:snippets` + +These filters can be combined as well. For example: Use `@installed @category:themes` to view all installed themes. + +If no filter is provided, the Extensions view displays the currently installed and recommended extensions. + +### Sorting + +You can sort extensions with the `@sort` filter which can take the following values: + +* `installs` - Sort by Marketplace installation count, in descending order. +* `rating` - Sort by Marketplace rating (1-5 stars), in descending order. +* `name` - Sort alphabetically by extension name. + +![sort by install count](images/extension-gallery/sort-install-count.png) + +### Categories and tags + +Extensions can set **Categories** and **Tags** describing their features. + +![extension categories and tags](images/extension-gallery/categories-and-tags.png) + +You can filter on category and tag by using `category:` and `tag:`. + +Supported categories are: `[Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs]`. They can be accessed through IntelliSense in the extensions search box: + +![categories debuggers](images/extension-gallery/extension-search-categories.png) + +Note that you must surround the category name in quotes if it is more than one word (for example, `category:"SCM Providers"`). + +Tags may contain any string and are not provided by IntelliSense so review the Marketplace to find helpful tags. + +## Install from a VSIX + +You can manually install a VS Code extension packaged in a `.vsix` file. Using the **Install from VSIX** command in the Extensions view command drop-down, or the **Extensions: Install from VSIX** command in the **Command Palette**, point to the `.vsix` file. + +You can also install using the VS Code `--install-extension` command line switch providing the path to the `.vsix` file. + +``` +code --install-extension myextension.vsix +``` + +You may provide the `--install-extension` multiple times on the command line to install multiple extensions at once. + +If you'd like to learn more about packaging and publishing extensions, see our [Publishing Extensions](/api/working-with-extensions/publishing-extension.md) topic in the Extension API. + +## Workspace recommended extensions + +A good set of extensions can make working with a particular workspace or programming language more productive and you'd often like to share this list with your team or colleagues. You can create a recommended list of extensions for a workspace with the **Extensions: Configure Recommended Extensions (Workspace)** command. + +In a single folder workspace, the command creates an `extensions.json` file located in the workspace `.vscode` folder where you can add a list of extensions identifiers ({publisherName}.{extensionName}). + +In a [multi-root workspace](/docs/editor/multi-root-workspaces.md), the command will open your `.code-workspace` file where you can list extensions under `extensions.recommendations`. You can still add extension recommendations to individual folders in a multi-root workspace by using the **Extensions: Configure Recommended Extensions (Workspace Folder)** command. + +An example `extensions.json` could be: + +```json +{ + "recommendations": [ + "ms-vscode.vscode-typescript-tslint-plugin", + "dbaeumer.vscode-eslint", + "msjsdiag.debugger-for-chrome" + ] +} +``` + +which recommends two linter extensions, TSLint and ESLint, as well as the Chrome debugger extension. + +An extension is identified using its publisher name and extension identifier `publisher.extension`. You can see the name on the extension's detail page. VS Code will provide you auto-completion for installed extensions inside these files. + +![Extension identifier](images/extension-gallery/extension-identifier.png). + +VS Code prompts a user to install the recommended extensions when a workspace is opened for the first time. The user can also review the list with the **Extensions: Show Recommended Extensions** command. + +![Show Recommendations](images/extension-gallery/recommendations.png) + +## Next steps + +Here are a few topics you may find interesting... + +* [Extension API](/api) - Start learning about the VS Code extension API. +* [Your First Extension](/api/get-started/your-first-extension.md) - Try creating a simple Hello World extension. +* [Publishing to the Marketplace](/api/working-with-extensions/publishing-extension.md) - Publish your own extension to the VS Code Marketplace. + +## Common questions + +### Where are extensions installed? + +Extensions are installed in a per user extensions folder. Depending on your platform, the location is in the following folder: + +* **Windows** `%USERPROFILE%\.vscode\extensions` +* **macOS** `~/.vscode/extensions` +* **Linux** `~/.vscode/extensions` + +You can change the location by launching VS Code with the `--extensions-dir ` command line [option](/docs/editor/command-line.md). + +### Whenever I try to install any extension, I get a connect ETIMEDOUT error + +You may see this error if your machine is going through a proxy server to access the Internet. See the [Proxy server support](/docs/setup/network.md#proxy-server-support) section in the setup topic for details. + +### Can I download an extension directly from the Marketplace? + +Some users prefer to download an extension once from the Marketplace and then install it multiple times from a local share. This is useful when there are connectivity concerns or if your development team wants to use a fixed set of extensions. + +To download an extension, navigate to the details page for the specific extension within the [Marketplace](https://marketplace.visualstudio.com/vscode). On that page, there is a **Download Extension** link in the **Resources** section which is located on the right hand side of the page. + +Once downloaded, you can then install the extension via the **Install from VSIX** command in the Extensions view command drop-down. + +### Can I stop VS Code from providing extension recommendations? + +Yes, if you would prefer to not have VS Code display extension recommendations in the Extensions view or through notifications, you can modify the following settings: + +* `extensions.showRecommendationsOnlyOnDemand` - Set to true to remove the **RECOMMENDED** section. +* `extensions.ignoreRecommendations` - Set to true to silence extension recommendation notifications. + +The **Show Recommended Extensions** command is always available if you wish to see recommendations. diff --git a/docs/editor/images/accessibility/high-contrast.png b/docs/editor/images/accessibility/high-contrast.png new file mode 100644 index 0000000000000000000000000000000000000000..64f391175043fd90b0b2d3d90c539f0e07e1a799 Binary files /dev/null and b/docs/editor/images/accessibility/high-contrast.png differ diff --git a/docs/editor/images/accessibility/keyboard-shortcuts.png b/docs/editor/images/accessibility/keyboard-shortcuts.png new file mode 100644 index 0000000000000000000000000000000000000000..d530598fcf7e3c123dc73a2d8ef5c1db824234d2 Binary files /dev/null and b/docs/editor/images/accessibility/keyboard-shortcuts.png differ diff --git a/docs/editor/images/accessibility/screen-reader-mode.png b/docs/editor/images/accessibility/screen-reader-mode.png new file mode 100644 index 0000000000000000000000000000000000000000..98aad160ff65e79c7df41e87479d1b08a51869b7 Binary files /dev/null and b/docs/editor/images/accessibility/screen-reader-mode.png differ diff --git a/docs/editor/images/accessibility/status.png b/docs/editor/images/accessibility/status.png new file mode 100644 index 0000000000000000000000000000000000000000..9bbacbcc4adc461379cb22e2a7415ec713c85ec1 Binary files /dev/null and b/docs/editor/images/accessibility/status.png differ diff --git a/docs/editor/images/accessibility/tab-moves-focus.png b/docs/editor/images/accessibility/tab-moves-focus.png new file mode 100644 index 0000000000000000000000000000000000000000..d2d463959cb279de6131e6d6cbb66b6d145709f1 Binary files /dev/null and b/docs/editor/images/accessibility/tab-moves-focus.png differ diff --git a/docs/editor/images/accessibility/zoomed-in.png b/docs/editor/images/accessibility/zoomed-in.png new file mode 100644 index 0000000000000000000000000000000000000000..94fc6781b03723f9bace6cf7780154b1d94f1c60 --- /dev/null +++ b/docs/editor/images/accessibility/zoomed-in.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:faace1665aab914c4e28b523e6fd9571545700bffb1751b5699caeb59ffebcae +size 136170 diff --git a/docs/editor/images/codebasics/CodeBasics.png b/docs/editor/images/codebasics/CodeBasics.png new file mode 100644 index 0000000000000000000000000000000000000000..6707bffc75314b77142e79c6b8a128fe62921a2e --- /dev/null +++ b/docs/editor/images/codebasics/CodeBasics.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:42494eb1538504753b62e25862c51758e30ddfb4f63655ba810fdad3152e9669 +size 148681 diff --git a/docs/editor/images/codebasics/column-select.gif b/docs/editor/images/codebasics/column-select.gif new file mode 100644 index 0000000000000000000000000000000000000000..0d942a0c3ec645ad7e2e4db20c222487f0dbb0ae --- /dev/null +++ b/docs/editor/images/codebasics/column-select.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1e8fc95ffc3417809f38c6ce036f01b632699dcc66980993b977510e1b538173 +size 128337 diff --git a/docs/editor/images/codebasics/encodingclicked.png b/docs/editor/images/codebasics/encodingclicked.png new file mode 100644 index 0000000000000000000000000000000000000000..0cd2d4a3d1485dc8e31bb4252277bcf0256be6d7 Binary files /dev/null and b/docs/editor/images/codebasics/encodingclicked.png differ diff --git a/docs/editor/images/codebasics/encodingselection.png b/docs/editor/images/codebasics/encodingselection.png new file mode 100644 index 0000000000000000000000000000000000000000..2d296fd591f525c5bfec1006f292b60d0d4a422e Binary files /dev/null and b/docs/editor/images/codebasics/encodingselection.png differ diff --git a/docs/editor/images/codebasics/expandselection.gif b/docs/editor/images/codebasics/expandselection.gif new file mode 100644 index 0000000000000000000000000000000000000000..8d411643dbd2d13fa3787cfbdbe1f42bd3b3a789 Binary files /dev/null and b/docs/editor/images/codebasics/expandselection.gif differ diff --git a/docs/editor/images/codebasics/fileencoding.png b/docs/editor/images/codebasics/fileencoding.png new file mode 100644 index 0000000000000000000000000000000000000000..dfd7a2d7ed2504f42df1375b86300b8bd65c1220 Binary files /dev/null and b/docs/editor/images/codebasics/fileencoding.png differ diff --git a/docs/editor/images/codebasics/filesencodingsetting.png b/docs/editor/images/codebasics/filesencodingsetting.png new file mode 100644 index 0000000000000000000000000000000000000000..8e4bfb8a236a900d826f229b1d0d353744baf23a Binary files /dev/null and b/docs/editor/images/codebasics/filesencodingsetting.png differ diff --git a/docs/editor/images/codebasics/folding.png b/docs/editor/images/codebasics/folding.png new file mode 100644 index 0000000000000000000000000000000000000000..8b66a7c7cf4163779e7ed92d8b65d6e8fd1ed545 Binary files /dev/null and b/docs/editor/images/codebasics/folding.png differ diff --git a/docs/editor/images/codebasics/global-search-replace.png b/docs/editor/images/codebasics/global-search-replace.png new file mode 100644 index 0000000000000000000000000000000000000000..5b4a5cb5ce6a0e1794057332286c0c4f7973b0a9 Binary files /dev/null and b/docs/editor/images/codebasics/global-search-replace.png differ diff --git a/docs/editor/images/codebasics/indentation-commands.png b/docs/editor/images/codebasics/indentation-commands.png new file mode 100644 index 0000000000000000000000000000000000000000..c1174f8ea0fe106696ee580c05829aaf20b4a593 Binary files /dev/null and b/docs/editor/images/codebasics/indentation-commands.png differ diff --git a/docs/editor/images/codebasics/indentation-detection.png b/docs/editor/images/codebasics/indentation-detection.png new file mode 100644 index 0000000000000000000000000000000000000000..bea40051c98521f1d2fda13732f28a40d16e800c Binary files /dev/null and b/docs/editor/images/codebasics/indentation-detection.png differ diff --git a/docs/editor/images/codebasics/multicursor-word.gif b/docs/editor/images/codebasics/multicursor-word.gif new file mode 100644 index 0000000000000000000000000000000000000000..b4acc4d68b80df29c4ed6da8eaf680fb08a0960d --- /dev/null +++ b/docs/editor/images/codebasics/multicursor-word.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fc990b95e9aa0566680683843b3f9129043d4adf4c9be8de7f9100b89eb89fd2 +size 416547 diff --git a/docs/editor/images/codebasics/multicursor.gif b/docs/editor/images/codebasics/multicursor.gif new file mode 100644 index 0000000000000000000000000000000000000000..680e3dd7027b4be24c912e3c01fec2fdd6055fd6 --- /dev/null +++ b/docs/editor/images/codebasics/multicursor.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3dc142ad24bbf6996a1e99cc257a362a2dc94b8afcb14d129668020aeb74b6d6 +size 183900 diff --git a/docs/editor/images/codebasics/search-replace-example.png b/docs/editor/images/codebasics/search-replace-example.png new file mode 100644 index 0000000000000000000000000000000000000000..1deddc9f90843046e973a350bd9cdf542006c885 Binary files /dev/null and b/docs/editor/images/codebasics/search-replace-example.png differ diff --git a/docs/editor/images/codebasics/search.png b/docs/editor/images/codebasics/search.png new file mode 100644 index 0000000000000000000000000000000000000000..589b15b60d753f3405916a18081146ece5be1bb7 Binary files /dev/null and b/docs/editor/images/codebasics/search.png differ diff --git a/docs/editor/images/codebasics/searchadvanced.png b/docs/editor/images/codebasics/searchadvanced.png new file mode 100644 index 0000000000000000000000000000000000000000..1f2bc0cc3fd6c450e1b78c449ba6038c93e2927a Binary files /dev/null and b/docs/editor/images/codebasics/searchadvanced.png differ diff --git a/docs/editor/images/command-line/goto-line-column.png b/docs/editor/images/command-line/goto-line-column.png new file mode 100644 index 0000000000000000000000000000000000000000..3451dc8ab074d095edf268145f646bc07c16188b Binary files /dev/null and b/docs/editor/images/command-line/goto-line-column.png differ diff --git a/docs/editor/images/command-line/hero.png b/docs/editor/images/command-line/hero.png new file mode 100644 index 0000000000000000000000000000000000000000..780921d4092c5cbbc36ff281cbfb077dbeda84e7 Binary files /dev/null and b/docs/editor/images/command-line/hero.png differ diff --git a/docs/editor/images/command-line/install-extension.png b/docs/editor/images/command-line/install-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..4729b57db87e3d8275a17c556e57deab714fd007 Binary files /dev/null and b/docs/editor/images/command-line/install-extension.png differ diff --git a/docs/editor/images/command-line/launch-locale.png b/docs/editor/images/command-line/launch-locale.png new file mode 100644 index 0000000000000000000000000000000000000000..b4368bfeeb2a6f22baafe62be1d0c2b456c3df49 Binary files /dev/null and b/docs/editor/images/command-line/launch-locale.png differ diff --git a/docs/editor/images/command-line/launch-vscode.png b/docs/editor/images/command-line/launch-vscode.png new file mode 100644 index 0000000000000000000000000000000000000000..2b5e1e6d1840bf27a41fb294965090bba005b7c0 Binary files /dev/null and b/docs/editor/images/command-line/launch-vscode.png differ diff --git a/docs/editor/images/command-line/vscode-url.png b/docs/editor/images/command-line/vscode-url.png new file mode 100644 index 0000000000000000000000000000000000000000..dee443f78bdaa51ca3c15e301b4f3d1903801c09 Binary files /dev/null and b/docs/editor/images/command-line/vscode-url.png differ diff --git a/docs/editor/images/debugging/Debugging.png b/docs/editor/images/debugging/Debugging.png new file mode 100644 index 0000000000000000000000000000000000000000..08287ca2d855f1dc9cf3556bdee53c00bac2dc45 --- /dev/null +++ b/docs/editor/images/debugging/Debugging.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:13c95b9be16778ab418670b71d9d9b2561a8aa8432c68f1595b553555862d5bb +size 146031 diff --git a/docs/editor/images/debugging/add-config.gif b/docs/editor/images/debugging/add-config.gif new file mode 100644 index 0000000000000000000000000000000000000000..325f514b2dcff705f1e43785446600ecd13132cf --- /dev/null +++ b/docs/editor/images/debugging/add-config.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2e11d0563095d857b60027c37d7bbd03f71f8e91c690c0bbee85b2a16c11f006 +size 124613 diff --git a/docs/editor/images/debugging/breakpoints.png b/docs/editor/images/debugging/breakpoints.png new file mode 100644 index 0000000000000000000000000000000000000000..278a500d4434746726a75590669db18a2e313084 Binary files /dev/null and b/docs/editor/images/debugging/breakpoints.png differ diff --git a/docs/editor/images/debugging/debug-actions-widget.png b/docs/editor/images/debugging/debug-actions-widget.png new file mode 100644 index 0000000000000000000000000000000000000000..09033971bb3631f0dcbde1b9e394c6a9563b48b6 Binary files /dev/null and b/docs/editor/images/debugging/debug-actions-widget.png differ diff --git a/docs/editor/images/debugging/debug-callstack.png b/docs/editor/images/debugging/debug-callstack.png new file mode 100644 index 0000000000000000000000000000000000000000..bb70825ed80c39d9d833f8951c00ee163c549ce9 Binary files /dev/null and b/docs/editor/images/debugging/debug-callstack.png differ diff --git a/docs/editor/images/debugging/debug-environments.png b/docs/editor/images/debugging/debug-environments.png new file mode 100644 index 0000000000000000000000000000000000000000..e15698d42e339dbc766b282a90d196d3d67afcb8 Binary files /dev/null and b/docs/editor/images/debugging/debug-environments.png differ diff --git a/docs/editor/images/debugging/debug-menu.png b/docs/editor/images/debugging/debug-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..26fd0a160706e82002688f4e14a4941a5f6dc05b Binary files /dev/null and b/docs/editor/images/debugging/debug-menu.png differ diff --git a/docs/editor/images/debugging/debug-session.png b/docs/editor/images/debugging/debug-session.png new file mode 100644 index 0000000000000000000000000000000000000000..52fc7884c51a717fcb1586a9a5aed18a6d05a4a2 Binary files /dev/null and b/docs/editor/images/debugging/debug-session.png differ diff --git a/docs/editor/images/debugging/debug-status.png b/docs/editor/images/debugging/debug-status.png new file mode 100644 index 0000000000000000000000000000000000000000..9f4e6bd5ed67e8f097eb30167da3f93d24d8a5f9 Binary files /dev/null and b/docs/editor/images/debugging/debug-status.png differ diff --git a/docs/editor/images/debugging/debugconsole.png b/docs/editor/images/debugging/debugconsole.png new file mode 100644 index 0000000000000000000000000000000000000000..7447a3ab41cf4403529d6876deeae8d6ed106973 Binary files /dev/null and b/docs/editor/images/debugging/debugconsole.png differ diff --git a/docs/editor/images/debugging/debugging_hero.png b/docs/editor/images/debugging/debugging_hero.png new file mode 100644 index 0000000000000000000000000000000000000000..47ee86faaa75299a70108c2fd603f7a68beaf037 Binary files /dev/null and b/docs/editor/images/debugging/debugging_hero.png differ diff --git a/docs/editor/images/debugging/debugicon.png b/docs/editor/images/debugging/debugicon.png new file mode 100644 index 0000000000000000000000000000000000000000..72075cab19603ea140f23a6f9487ecd2abf29f58 Binary files /dev/null and b/docs/editor/images/debugging/debugicon.png differ diff --git a/docs/editor/images/debugging/hitCount.gif b/docs/editor/images/debugging/hitCount.gif new file mode 100644 index 0000000000000000000000000000000000000000..bd048504ffe5f2ebefc2ab55fce30717f7765583 --- /dev/null +++ b/docs/editor/images/debugging/hitCount.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6b4d63d019b23acdaa93936553043fb212c909c490c4ae6d934fed796483792a +size 217290 diff --git a/docs/editor/images/debugging/launch-configuration.png b/docs/editor/images/debugging/launch-configuration.png new file mode 100644 index 0000000000000000000000000000000000000000..fb694e08ad25e2a72b6a4827e0db9f572c5b605e Binary files /dev/null and b/docs/editor/images/debugging/launch-configuration.png differ diff --git a/docs/editor/images/debugging/launch-json-in-explorer.png b/docs/editor/images/debugging/launch-json-in-explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..4dd0d55d3f9674086fc79bde3edd268ca843f39c Binary files /dev/null and b/docs/editor/images/debugging/launch-json-in-explorer.png differ diff --git a/docs/editor/images/debugging/launch-json-intellisense.png b/docs/editor/images/debugging/launch-json-intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..f7fc506eed128454e8005770be82eb27cf3d4839 --- /dev/null +++ b/docs/editor/images/debugging/launch-json-intellisense.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:11ee8f1787799e1f7c6b02a2f5cc143c0df21ce269060ebd639b7b955bf28c6b +size 111543 diff --git a/docs/editor/images/debugging/launch-json-suggestions.png b/docs/editor/images/debugging/launch-json-suggestions.png new file mode 100644 index 0000000000000000000000000000000000000000..e77fbd29b17a8c5d0138d56e249f0dc53849b0b1 Binary files /dev/null and b/docs/editor/images/debugging/launch-json-suggestions.png differ diff --git a/docs/editor/images/debugging/log-points.gif b/docs/editor/images/debugging/log-points.gif new file mode 100644 index 0000000000000000000000000000000000000000..e67e69a5112b483c2f2029bb7aeac16785231ba5 --- /dev/null +++ b/docs/editor/images/debugging/log-points.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e76666140552dc88e5394f66d4d54e36d26edb0ae43eaed79990b093baa9219d +size 1632370 diff --git a/docs/editor/images/debugging/toolbar.png b/docs/editor/images/debugging/toolbar.png new file mode 100644 index 0000000000000000000000000000000000000000..754e68e03fbe5eff10db43c4c97871faf02d3184 Binary files /dev/null and b/docs/editor/images/debugging/toolbar.png differ diff --git a/docs/editor/images/debugging/variables.png b/docs/editor/images/debugging/variables.png new file mode 100644 index 0000000000000000000000000000000000000000..3274069c7f9066fb52d70ce078174c72260ebff9 Binary files /dev/null and b/docs/editor/images/debugging/variables.png differ diff --git a/docs/editor/images/debugging/watch.png b/docs/editor/images/debugging/watch.png new file mode 100644 index 0000000000000000000000000000000000000000..c421fd46c8290bb04b68334fe1241266006fb5bd Binary files /dev/null and b/docs/editor/images/debugging/watch.png differ diff --git a/docs/editor/images/editingevolved/brackets.png b/docs/editor/images/editingevolved/brackets.png new file mode 100644 index 0000000000000000000000000000000000000000..619612ef4d1b23feb367e328fb737baef4aeea30 Binary files /dev/null and b/docs/editor/images/editingevolved/brackets.png differ diff --git a/docs/editor/images/editingevolved/ctrlhover.png b/docs/editor/images/editingevolved/ctrlhover.png new file mode 100644 index 0000000000000000000000000000000000000000..75481988bc1231527eddc7f2cfff8b42fb5065ac Binary files /dev/null and b/docs/editor/images/editingevolved/ctrlhover.png differ diff --git a/docs/editor/images/editingevolved/emmetsnippet.gif b/docs/editor/images/editingevolved/emmetsnippet.gif new file mode 100644 index 0000000000000000000000000000000000000000..44b0bbe47472815c8a2add3c96c077de17ac75f1 Binary files /dev/null and b/docs/editor/images/editingevolved/emmetsnippet.gif differ diff --git a/docs/editor/images/editingevolved/errors.png b/docs/editor/images/editingevolved/errors.png new file mode 100644 index 0000000000000000000000000000000000000000..b351bfcb00c8839b7de056d379d81324972ffeaf Binary files /dev/null and b/docs/editor/images/editingevolved/errors.png differ diff --git a/docs/editor/images/editingevolved/errorsinline.png b/docs/editor/images/editingevolved/errorsinline.png new file mode 100644 index 0000000000000000000000000000000000000000..0d31eeb2b12dc754411f427e1d0a3e4b8a6f7526 Binary files /dev/null and b/docs/editor/images/editingevolved/errorsinline.png differ diff --git a/docs/editor/images/editingevolved/gotosymbol.png b/docs/editor/images/editingevolved/gotosymbol.png new file mode 100644 index 0000000000000000000000000000000000000000..c4261c7621d751d964b52bb5e48b4871a7f7d033 Binary files /dev/null and b/docs/editor/images/editingevolved/gotosymbol.png differ diff --git a/docs/editor/images/editingevolved/gutter.png b/docs/editor/images/editingevolved/gutter.png new file mode 100644 index 0000000000000000000000000000000000000000..c2ad59bb0659b17f3213688802c88da47e790106 Binary files /dev/null and b/docs/editor/images/editingevolved/gutter.png differ diff --git a/docs/editor/images/editingevolved/hover.png b/docs/editor/images/editingevolved/hover.png new file mode 100644 index 0000000000000000000000000000000000000000..34c107493fcde020f66b6ff059ce0e1431279a39 Binary files /dev/null and b/docs/editor/images/editingevolved/hover.png differ diff --git a/docs/editor/images/editingevolved/intellisense.png b/docs/editor/images/editingevolved/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..4dfb081f7ad950fff767410be9ac82b0fe182425 Binary files /dev/null and b/docs/editor/images/editingevolved/intellisense.png differ diff --git a/docs/editor/images/editingevolved/javascript-intellisense.png b/docs/editor/images/editingevolved/javascript-intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..080755d9ccf9367662e42c4837361018ce37df48 Binary files /dev/null and b/docs/editor/images/editingevolved/javascript-intellisense.png differ diff --git a/docs/editor/images/editingevolved/parameterhints.png b/docs/editor/images/editingevolved/parameterhints.png new file mode 100644 index 0000000000000000000000000000000000000000..a78a4b193aa66fb52cd92d56590528c35b1c3572 Binary files /dev/null and b/docs/editor/images/editingevolved/parameterhints.png differ diff --git a/docs/editor/images/editingevolved/quicknav.png b/docs/editor/images/editingevolved/quicknav.png new file mode 100644 index 0000000000000000000000000000000000000000..8e1cf150d6c0e379c6643e1226eb9e3e5728c5b6 Binary files /dev/null and b/docs/editor/images/editingevolved/quicknav.png differ diff --git a/docs/editor/images/editingevolved/referenceinfo.png b/docs/editor/images/editingevolved/referenceinfo.png new file mode 100644 index 0000000000000000000000000000000000000000..a93d10e8a67f29cb571e4d3d3c950ad157b13ae7 Binary files /dev/null and b/docs/editor/images/editingevolved/referenceinfo.png differ diff --git a/docs/editor/images/editingevolved/references.png b/docs/editor/images/editingevolved/references.png new file mode 100644 index 0000000000000000000000000000000000000000..00ac5b42fbf49394a6666c7b947c4de69c16c2d7 Binary files /dev/null and b/docs/editor/images/editingevolved/references.png differ diff --git a/docs/editor/images/editingevolved/rename.png b/docs/editor/images/editingevolved/rename.png new file mode 100644 index 0000000000000000000000000000000000000000..540a93b589f86e16d5996a341b55d93c228ef6f9 Binary files /dev/null and b/docs/editor/images/editingevolved/rename.png differ diff --git a/docs/editor/images/editingevolved/symbol.png b/docs/editor/images/editingevolved/symbol.png new file mode 100644 index 0000000000000000000000000000000000000000..fa628537e609b1b7da82d996e62317079050f77a Binary files /dev/null and b/docs/editor/images/editingevolved/symbol.png differ diff --git a/docs/editor/images/emmet/emmet-multi-cursor.gif b/docs/editor/images/emmet/emmet-multi-cursor.gif new file mode 100644 index 0000000000000000000000000000000000000000..3f35f0293c5a790992d87a739d58972f64290315 --- /dev/null +++ b/docs/editor/images/emmet/emmet-multi-cursor.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7e7e7dff8162193a30a8d23ea69de9602013f7113cadafcc111afe6d1e1ac10e +size 1020513 diff --git a/docs/editor/images/emmet/emmet-vendor-prefix.gif b/docs/editor/images/emmet/emmet-vendor-prefix.gif new file mode 100644 index 0000000000000000000000000000000000000000..98fff4236d114dc19ecc9fee3698763821f25380 --- /dev/null +++ b/docs/editor/images/emmet/emmet-vendor-prefix.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3aded42f660be0eadc445880ab55c5bd823193fff165826e79ee721fa1a48b84 +size 465268 diff --git a/docs/editor/images/emmet/emmet.gif b/docs/editor/images/emmet/emmet.gif new file mode 100644 index 0000000000000000000000000000000000000000..40a58546127ce4a094471923adc15dedca6c085c --- /dev/null +++ b/docs/editor/images/emmet/emmet.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:82f194f2b74764015768c47308feeaec03ef3484242357d2d870a2e38a20a117 +size 194330 diff --git a/docs/editor/images/extension-gallery/categories-and-tags.png b/docs/editor/images/extension-gallery/categories-and-tags.png new file mode 100644 index 0000000000000000000000000000000000000000..394a698354194ed6b4cf25d150f261174f362a7f Binary files /dev/null and b/docs/editor/images/extension-gallery/categories-and-tags.png differ diff --git a/docs/editor/images/extension-gallery/categories-debuggers.png b/docs/editor/images/extension-gallery/categories-debuggers.png new file mode 100644 index 0000000000000000000000000000000000000000..d4b0bd7636efd08b8b4f9f99cbce2836747074ec Binary files /dev/null and b/docs/editor/images/extension-gallery/categories-debuggers.png differ diff --git a/docs/editor/images/extension-gallery/disable-extension.png b/docs/editor/images/extension-gallery/disable-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..dc4ec1a83c33f1dc2b3122b1df08b61f99ff2b32 --- /dev/null +++ b/docs/editor/images/extension-gallery/disable-extension.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6fad8718963ec91faf0c7c1ee71b129b8da3e02915f2727322e5f919a2e4d7aa +size 147549 diff --git a/docs/editor/images/extension-gallery/enable-extension.png b/docs/editor/images/extension-gallery/enable-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..4f622aafd1d72010a67de4371d2d5625a20f4559 --- /dev/null +++ b/docs/editor/images/extension-gallery/enable-extension.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9d1cc3d3744eca7fbb66ec849c915330b60e61e43da45ca021b4671cda8a0541 +size 135995 diff --git a/docs/editor/images/extension-gallery/extension-contributions.png b/docs/editor/images/extension-gallery/extension-contributions.png new file mode 100644 index 0000000000000000000000000000000000000000..a91cbf8eb36893af1ce38e58fd59fcce2c885654 Binary files /dev/null and b/docs/editor/images/extension-gallery/extension-contributions.png differ diff --git a/docs/editor/images/extension-gallery/extension-dependencies.png b/docs/editor/images/extension-gallery/extension-dependencies.png new file mode 100644 index 0000000000000000000000000000000000000000..f63633a0fb7613513653b973ce92fe71693eb45d Binary files /dev/null and b/docs/editor/images/extension-gallery/extension-dependencies.png differ diff --git a/docs/editor/images/extension-gallery/extension-identifier.png b/docs/editor/images/extension-gallery/extension-identifier.png new file mode 100644 index 0000000000000000000000000000000000000000..d5bd23e192cc0cc35dcc6161a606789808aa0ff5 Binary files /dev/null and b/docs/editor/images/extension-gallery/extension-identifier.png differ diff --git a/docs/editor/images/extension-gallery/extension-pack.png b/docs/editor/images/extension-gallery/extension-pack.png new file mode 100644 index 0000000000000000000000000000000000000000..813cb86dad47113f15899fe8659acadcbba93d11 Binary files /dev/null and b/docs/editor/images/extension-gallery/extension-pack.png differ diff --git a/docs/editor/images/extension-gallery/extension-search-categories.png b/docs/editor/images/extension-gallery/extension-search-categories.png new file mode 100644 index 0000000000000000000000000000000000000000..3adca9ef870da9168d0ad31471d3fcef2889628c --- /dev/null +++ b/docs/editor/images/extension-gallery/extension-search-categories.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bc334fab62f028b9b7ffe35626dd577ff396482167711c6216f811475488be1e +size 100374 diff --git a/docs/editor/images/extension-gallery/extension-search-filters.png b/docs/editor/images/extension-gallery/extension-search-filters.png new file mode 100644 index 0000000000000000000000000000000000000000..9659f90ae68c5531d188d6cb71e2e23fc0817b05 Binary files /dev/null and b/docs/editor/images/extension-gallery/extension-search-filters.png differ diff --git a/docs/editor/images/extension-gallery/extensions-disable-all.gif b/docs/editor/images/extension-gallery/extensions-disable-all.gif new file mode 100644 index 0000000000000000000000000000000000000000..92e815fc09588c22b84a4eadfbb6db236d2f984a --- /dev/null +++ b/docs/editor/images/extension-gallery/extensions-disable-all.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:21e6a2d66e9fdb6ac2204d34044e0e9c7a7852ad67093fe36b4e688351a343f5 +size 443083 diff --git a/docs/editor/images/extension-gallery/extensions-disable.gif b/docs/editor/images/extension-gallery/extensions-disable.gif new file mode 100644 index 0000000000000000000000000000000000000000..3603dcf31ecf1ec36fe7bd4e92cf8e278637b638 --- /dev/null +++ b/docs/editor/images/extension-gallery/extensions-disable.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cc84f8ec8349d025f4ac391d079102a3b7fca8bfc5e2d46a7ce1f8fcf32ec808 +size 100348 diff --git a/docs/editor/images/extension-gallery/extensions-popular.png b/docs/editor/images/extension-gallery/extensions-popular.png new file mode 100644 index 0000000000000000000000000000000000000000..2fa11a9b7796099212c249aaf388d3f30459d06e --- /dev/null +++ b/docs/editor/images/extension-gallery/extensions-popular.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c68e776c804b9e9946f211d53ababafc90f3ec5e18ef1dbb7a18912601249867 +size 150060 diff --git a/docs/editor/images/extension-gallery/extensions-python.png b/docs/editor/images/extension-gallery/extensions-python.png new file mode 100644 index 0000000000000000000000000000000000000000..0a39bebff1b296e7d6e2359235b13b225858cce5 --- /dev/null +++ b/docs/editor/images/extension-gallery/extensions-python.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:39ee09f601aeed3070875fb4e279e285df7a57d37fb2fc59b485a18fbe015c3c +size 103411 diff --git a/docs/editor/images/extension-gallery/extensions-view-icon.png b/docs/editor/images/extension-gallery/extensions-view-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..59daa52e656823c63ac5a4676d063afd0c0bb1d4 Binary files /dev/null and b/docs/editor/images/extension-gallery/extensions-view-icon.png differ diff --git a/docs/editor/images/extension-gallery/ignore-recommendation.png b/docs/editor/images/extension-gallery/ignore-recommendation.png new file mode 100644 index 0000000000000000000000000000000000000000..5cd57adee052cf4c9fa88c5366b086f1cadaeacf Binary files /dev/null and b/docs/editor/images/extension-gallery/ignore-recommendation.png differ diff --git a/docs/editor/images/extension-gallery/marketplace-categories.png b/docs/editor/images/extension-gallery/marketplace-categories.png new file mode 100644 index 0000000000000000000000000000000000000000..dc41123915bb39cb83fc11d1f6a04c0db29b7ab8 Binary files /dev/null and b/docs/editor/images/extension-gallery/marketplace-categories.png differ diff --git a/docs/editor/images/extension-gallery/marketplace.png b/docs/editor/images/extension-gallery/marketplace.png new file mode 100644 index 0000000000000000000000000000000000000000..1b26f1a477c71d1d03f55e9eb93ba2c11fb91e9a Binary files /dev/null and b/docs/editor/images/extension-gallery/marketplace.png differ diff --git a/docs/editor/images/extension-gallery/more-button.png b/docs/editor/images/extension-gallery/more-button.png new file mode 100644 index 0000000000000000000000000000000000000000..9b14915539c0e40cc9c51b289e46034f8b6a5b55 Binary files /dev/null and b/docs/editor/images/extension-gallery/more-button.png differ diff --git a/docs/editor/images/extension-gallery/more-dropdown.png b/docs/editor/images/extension-gallery/more-dropdown.png new file mode 100644 index 0000000000000000000000000000000000000000..01c0fa90d319ea1ec027d2133a3b3d1b69181e2e Binary files /dev/null and b/docs/editor/images/extension-gallery/more-dropdown.png differ diff --git a/docs/editor/images/extension-gallery/recommendations.png b/docs/editor/images/extension-gallery/recommendations.png new file mode 100644 index 0000000000000000000000000000000000000000..b4cbe21c917c4bda9785ebcffc5cc12cdd60c696 Binary files /dev/null and b/docs/editor/images/extension-gallery/recommendations.png differ diff --git a/docs/editor/images/extension-gallery/sort-install-count.png b/docs/editor/images/extension-gallery/sort-install-count.png new file mode 100644 index 0000000000000000000000000000000000000000..f978378a7776709d0b5f8250a3f4b6dcf16ea00a Binary files /dev/null and b/docs/editor/images/extension-gallery/sort-install-count.png differ diff --git a/docs/editor/images/extension-gallery/uninstall-extension.png b/docs/editor/images/extension-gallery/uninstall-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..72a533dded44ea14b0185b8bce4878af2f995939 --- /dev/null +++ b/docs/editor/images/extension-gallery/uninstall-extension.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:eafb81982efdf0998eef374a8924f527324dc9a1ef2435ecff3d086cee14fc26 +size 147562 diff --git a/docs/editor/images/integrated-terminal/integrated-terminal.png b/docs/editor/images/integrated-terminal/integrated-terminal.png new file mode 100644 index 0000000000000000000000000000000000000000..9cd33abe140e7154d55752201164ff6cf2b3e324 Binary files /dev/null and b/docs/editor/images/integrated-terminal/integrated-terminal.png differ diff --git a/docs/editor/images/integrated-terminal/terminal-multiple-instances.png b/docs/editor/images/integrated-terminal/terminal-multiple-instances.png new file mode 100644 index 0000000000000000000000000000000000000000..14da434bc9fa39327c650849d8785be2f83a1e6a Binary files /dev/null and b/docs/editor/images/integrated-terminal/terminal-multiple-instances.png differ diff --git a/docs/editor/images/integrated-terminal/terminal-split-pane.png b/docs/editor/images/integrated-terminal/terminal-split-pane.png new file mode 100644 index 0000000000000000000000000000000000000000..7e67d0696301e1fcf98e5b9834eca705346345a0 Binary files /dev/null and b/docs/editor/images/integrated-terminal/terminal-split-pane.png differ diff --git a/docs/editor/images/integrated-terminal/terminal_run_selected.png b/docs/editor/images/integrated-terminal/terminal_run_selected.png new file mode 100644 index 0000000000000000000000000000000000000000..e67b000b7d390b7853bd6170b5ccd323f3386b2d Binary files /dev/null and b/docs/editor/images/integrated-terminal/terminal_run_selected.png differ diff --git a/docs/editor/images/integrated-terminal/terminal_run_selected_result.png b/docs/editor/images/integrated-terminal/terminal_run_selected_result.png new file mode 100644 index 0000000000000000000000000000000000000000..317a143d5709e154a19cf50ae52e094b744b837a Binary files /dev/null and b/docs/editor/images/integrated-terminal/terminal_run_selected_result.png differ diff --git a/docs/editor/images/intellisense/Class_16x.svg b/docs/editor/images/intellisense/Class_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..daeb307f303b7d5d5ac6a2673547ee398bc180dd --- /dev/null +++ b/docs/editor/images/intellisense/Class_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/ColorPalette_16x.svg b/docs/editor/images/intellisense/ColorPalette_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..5a446ea9bdbd0c1edf8120a715b8a394b8de8a7d --- /dev/null +++ b/docs/editor/images/intellisense/ColorPalette_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/Document_16x.svg b/docs/editor/images/intellisense/Document_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..9e3d29abb75eb0c7b111fbebd069b8a653116fe0 --- /dev/null +++ b/docs/editor/images/intellisense/Document_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/EnumItem_16x.svg b/docs/editor/images/intellisense/EnumItem_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..ca70a61cb1f4ded4e698f5afd54a455a8a74125f --- /dev/null +++ b/docs/editor/images/intellisense/EnumItem_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/Enumerator_16x.svg b/docs/editor/images/intellisense/Enumerator_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..164a6ce52c854af96077d466ab5ce28e5e42599b --- /dev/null +++ b/docs/editor/images/intellisense/Enumerator_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/Field_16x.svg b/docs/editor/images/intellisense/Field_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..73222946dffa461dea417fbe448b28f293e3dabd --- /dev/null +++ b/docs/editor/images/intellisense/Field_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/IntelliSenseKeyword_16x.svg b/docs/editor/images/intellisense/IntelliSenseKeyword_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..8a40e246e315176982671bdfd1852e78d79e9cb8 --- /dev/null +++ b/docs/editor/images/intellisense/IntelliSenseKeyword_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/Interface_16x.svg b/docs/editor/images/intellisense/Interface_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..dd096ceda065f68fde8615c849f26275e56a2b13 --- /dev/null +++ b/docs/editor/images/intellisense/Interface_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/Method_16x.svg b/docs/editor/images/intellisense/Method_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..472538eaff7e75d17fbc5dc506f0dc1fefda88e0 --- /dev/null +++ b/docs/editor/images/intellisense/Method_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/Misc_16x.svg b/docs/editor/images/intellisense/Misc_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..74397f842014c4feaf290b72fda9c6135ef54708 --- /dev/null +++ b/docs/editor/images/intellisense/Misc_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/Namespace_16x.svg b/docs/editor/images/intellisense/Namespace_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..182360cd396ea2bf7196392c37839ef96fe4c2f8 --- /dev/null +++ b/docs/editor/images/intellisense/Namespace_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/Property_16x.svg b/docs/editor/images/intellisense/Property_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..27f3730b9b6c770d1a122d61aaf144b304a32405 --- /dev/null +++ b/docs/editor/images/intellisense/Property_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/Ruler_16x.svg b/docs/editor/images/intellisense/Ruler_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..a4e0c85ebab38c979770fbebe930fb92c363b2ba --- /dev/null +++ b/docs/editor/images/intellisense/Ruler_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/Snippet_16x.svg b/docs/editor/images/intellisense/Snippet_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..fdf8982e9ae23a5b8eb13649572074d3ea18bd56 --- /dev/null +++ b/docs/editor/images/intellisense/Snippet_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/String_16x.svg b/docs/editor/images/intellisense/String_16x.svg new file mode 100644 index 0000000000000000000000000000000000000000..c4653575ad8740933e6e532c58b02b72ae1ae540 --- /dev/null +++ b/docs/editor/images/intellisense/String_16x.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/editor/images/intellisense/intellisense.gif b/docs/editor/images/intellisense/intellisense.gif new file mode 100644 index 0000000000000000000000000000000000000000..670cc083dbebd772b71880d95c95276f50349f7c Binary files /dev/null and b/docs/editor/images/intellisense/intellisense.gif differ diff --git a/docs/editor/images/intellisense/intellisense_docs.gif b/docs/editor/images/intellisense/intellisense_docs.gif new file mode 100644 index 0000000000000000000000000000000000000000..aa2a9b93d23bf8ce8c2d2e63602668664ee5aa11 Binary files /dev/null and b/docs/editor/images/intellisense/intellisense_docs.gif differ diff --git a/docs/editor/images/intellisense/intellisense_error.png b/docs/editor/images/intellisense/intellisense_error.png new file mode 100644 index 0000000000000000000000000000000000000000..2e8585c84844172a0ff585232b98a9264cd2bab3 Binary files /dev/null and b/docs/editor/images/intellisense/intellisense_error.png differ diff --git a/docs/editor/images/intellisense/intellisense_icons.png b/docs/editor/images/intellisense/intellisense_icons.png new file mode 100644 index 0000000000000000000000000000000000000000..fb5eab76debd6dc0b6a64b02a228741878f7eacc Binary files /dev/null and b/docs/editor/images/intellisense/intellisense_icons.png differ diff --git a/docs/editor/images/intellisense/intellisense_packagejson.gif b/docs/editor/images/intellisense/intellisense_packagejson.gif new file mode 100644 index 0000000000000000000000000000000000000000..b6584ae185f9a8e2ed2c5b392514edd01c317baf Binary files /dev/null and b/docs/editor/images/intellisense/intellisense_packagejson.gif differ diff --git a/docs/editor/images/intellisense/localitybonus.png b/docs/editor/images/intellisense/localitybonus.png new file mode 100644 index 0000000000000000000000000000000000000000..c1f2a281c7cb207611bdd8b68eba430011a7dfb9 --- /dev/null +++ b/docs/editor/images/intellisense/localitybonus.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1a4af0b2eaf4dd2ada730ba139ee37ee558bfa30dbb02d49c617932a0141c3c3 +size 125478 diff --git a/docs/editor/images/intellisense/missing_typings.png b/docs/editor/images/intellisense/missing_typings.png new file mode 100644 index 0000000000000000000000000000000000000000..8024228dfa13301d1242c7c74c928ba88a7d5a85 Binary files /dev/null and b/docs/editor/images/intellisense/missing_typings.png differ diff --git a/docs/editor/images/intellisense/paramater_info.png b/docs/editor/images/intellisense/paramater_info.png new file mode 100644 index 0000000000000000000000000000000000000000..e8b1aeb9e8e61d83ccf96bdeb4a4c3813f535d45 Binary files /dev/null and b/docs/editor/images/intellisense/paramater_info.png differ diff --git a/docs/editor/images/intellisense/quick_outline.png b/docs/editor/images/intellisense/quick_outline.png new file mode 100644 index 0000000000000000000000000000000000000000..9311c51dc5ea9762c1f28b573ffa78a8b0c31ff6 Binary files /dev/null and b/docs/editor/images/intellisense/quick_outline.png differ diff --git a/docs/editor/images/intellisense/tabCompletion.gif b/docs/editor/images/intellisense/tabCompletion.gif new file mode 100644 index 0000000000000000000000000000000000000000..960b1766ad4ac24c1c6f3cbf322f35ccdd453f74 --- /dev/null +++ b/docs/editor/images/intellisense/tabCompletion.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:298201229ad002815526d839e619878f224cdf6892b24afd6a3fcd61f674ed2e +size 648558 diff --git a/docs/editor/images/keybinding/outline.png b/docs/editor/images/keybinding/outline.png new file mode 100644 index 0000000000000000000000000000000000000000..c22e9ff13784f70cbc91e1271be6bf9ced223d61 Binary files /dev/null and b/docs/editor/images/keybinding/outline.png differ diff --git a/docs/editor/images/multi-root-workspaces/add-config.png b/docs/editor/images/multi-root-workspaces/add-config.png new file mode 100644 index 0000000000000000000000000000000000000000..cc25ea4de346b7659910149cf966cdd0b12a2609 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/add-config.png differ diff --git a/docs/editor/images/multi-root-workspaces/add-launch-config.png b/docs/editor/images/multi-root-workspaces/add-launch-config.png new file mode 100644 index 0000000000000000000000000000000000000000..f8b2a0264fc7e56e7b9dcd5c3496cd1b17768f78 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/add-launch-config.png differ diff --git a/docs/editor/images/multi-root-workspaces/add-root-folder.png b/docs/editor/images/multi-root-workspaces/add-root-folder.png new file mode 100644 index 0000000000000000000000000000000000000000..a265ce4198ee66d8ddc717df6c90909da209aaab Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/add-root-folder.png differ diff --git a/docs/editor/images/multi-root-workspaces/debugging-dropdown.png b/docs/editor/images/multi-root-workspaces/debugging-dropdown.png new file mode 100644 index 0000000000000000000000000000000000000000..900ca1aa6bec91eac6da26235d510bf0a26c36da Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/debugging-dropdown.png differ diff --git a/docs/editor/images/multi-root-workspaces/explorer-context.png b/docs/editor/images/multi-root-workspaces/explorer-context.png new file mode 100644 index 0000000000000000000000000000000000000000..362cd3caca46bcc5c3761ce185d8edb237acf238 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/explorer-context.png differ diff --git a/docs/editor/images/multi-root-workspaces/hero.png b/docs/editor/images/multi-root-workspaces/hero.png new file mode 100644 index 0000000000000000000000000000000000000000..7401a9297f778ba2d9e468d21d5b02d13a6f4aef Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/hero.png differ diff --git a/docs/editor/images/multi-root-workspaces/multiple-scm-providers.png b/docs/editor/images/multi-root-workspaces/multiple-scm-providers.png new file mode 100644 index 0000000000000000000000000000000000000000..aceb33f90fecbec55179a6400903f77b57592048 --- /dev/null +++ b/docs/editor/images/multi-root-workspaces/multiple-scm-providers.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:975a66a07476b28e3587260d3cc27a03e18533224ec6cb04fc1535e3ed35e87a +size 118815 diff --git a/docs/editor/images/multi-root-workspaces/named-folders.png b/docs/editor/images/multi-root-workspaces/named-folders.png new file mode 100644 index 0000000000000000000000000000000000000000..2d742c1edada68db65a686f8bf04bc5035d5f8b5 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/named-folders.png differ diff --git a/docs/editor/images/multi-root-workspaces/open-recent.png b/docs/editor/images/multi-root-workspaces/open-recent.png new file mode 100644 index 0000000000000000000000000000000000000000..09f3ceea85508b0bd052aa06057aabf02dca6fd9 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/open-recent.png differ diff --git a/docs/editor/images/multi-root-workspaces/quick-open-list.png b/docs/editor/images/multi-root-workspaces/quick-open-list.png new file mode 100644 index 0000000000000000000000000000000000000000..658ac8a93da13c20a9a556555c82f0b4dea86bbc Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/quick-open-list.png differ diff --git a/docs/editor/images/multi-root-workspaces/save-workspace.png b/docs/editor/images/multi-root-workspaces/save-workspace.png new file mode 100644 index 0000000000000000000000000000000000000000..ec9bb2036e307fdb3293f58f5bf52611545f17b5 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/save-workspace.png differ diff --git a/docs/editor/images/multi-root-workspaces/search.png b/docs/editor/images/multi-root-workspaces/search.png new file mode 100644 index 0000000000000000000000000000000000000000..554751ad0384091be1f56a3ba182fa5868d0ac72 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/search.png differ diff --git a/docs/editor/images/multi-root-workspaces/settings-dropdown.png b/docs/editor/images/multi-root-workspaces/settings-dropdown.png new file mode 100644 index 0000000000000000000000000000000000000000..829dfa37d40455216aa021f0cbc248526f30ca49 --- /dev/null +++ b/docs/editor/images/multi-root-workspaces/settings-dropdown.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7cf978cf5e3ea8212b23086b131759350f7c3ac18fe105a8d4949537379ce348 +size 134572 diff --git a/docs/editor/images/multi-root-workspaces/tabbed-headers.png b/docs/editor/images/multi-root-workspaces/tabbed-headers.png new file mode 100644 index 0000000000000000000000000000000000000000..1788b5f33a274419848edc8be38225118a3d1d96 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/tabbed-headers.png differ diff --git a/docs/editor/images/multi-root-workspaces/tasks-dropdown.png b/docs/editor/images/multi-root-workspaces/tasks-dropdown.png new file mode 100644 index 0000000000000000000000000000000000000000..f58315052d90199af2daed7606c19702fa0d1b15 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/tasks-dropdown.png differ diff --git a/docs/editor/images/multi-root-workspaces/unsupported-setting-info.png b/docs/editor/images/multi-root-workspaces/unsupported-setting-info.png new file mode 100644 index 0000000000000000000000000000000000000000..5bfc8514dda8e74bcef7fcbcf71f437bffbbb88d Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/unsupported-setting-info.png differ diff --git a/docs/editor/images/multi-root-workspaces/workspace-file-schema.png b/docs/editor/images/multi-root-workspaces/workspace-file-schema.png new file mode 100644 index 0000000000000000000000000000000000000000..dc0137594a77d1ebcd9595c8e08e8e884dfcc8c8 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/workspace-file-schema.png differ diff --git a/docs/editor/images/multi-root-workspaces/workspace-icon.png b/docs/editor/images/multi-root-workspaces/workspace-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..c7e953e1fd21768a7a2bc7dd6bb4f9ae9262f353 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/workspace-icon.png differ diff --git a/docs/editor/images/multi-root-workspaces/workspace-settings.png b/docs/editor/images/multi-root-workspaces/workspace-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..d8f0051d9c2f0be5cc0ee60d170fdf90e6d9aae0 Binary files /dev/null and b/docs/editor/images/multi-root-workspaces/workspace-settings.png differ diff --git a/docs/editor/images/refactoring/code-action-context-menu.png b/docs/editor/images/refactoring/code-action-context-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..98f6d13387ebf89f7a5758d93690c0064318e712 Binary files /dev/null and b/docs/editor/images/refactoring/code-action-context-menu.png differ diff --git a/docs/editor/images/refactoring/refactoring-hero.png b/docs/editor/images/refactoring/refactoring-hero.png new file mode 100644 index 0000000000000000000000000000000000000000..c1b38eff9c619c688f49f47a80dcf413ebec5497 Binary files /dev/null and b/docs/editor/images/refactoring/refactoring-hero.png differ diff --git a/docs/editor/images/refactoring/rename.png b/docs/editor/images/refactoring/rename.png new file mode 100644 index 0000000000000000000000000000000000000000..06c5edd544ed33e5f198f3a71b0b5fffcc838a8d Binary files /dev/null and b/docs/editor/images/refactoring/rename.png differ diff --git a/docs/editor/images/refactoring/ts-extract-local.gif b/docs/editor/images/refactoring/ts-extract-local.gif new file mode 100644 index 0000000000000000000000000000000000000000..bcf27710e0c6bf09c702a846f129b7c6e58bd44e --- /dev/null +++ b/docs/editor/images/refactoring/ts-extract-local.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:39bed5a6de19d5ee35faeeb1e10377081d58a5deeda73e777d44d712a377b02e +size 5463780 diff --git a/docs/editor/images/tasks/command-palette.png b/docs/editor/images/tasks/command-palette.png new file mode 100644 index 0000000000000000000000000000000000000000..ff2758ea0b507ab639bcce1bb9c6c16e03806578 Binary files /dev/null and b/docs/editor/images/tasks/command-palette.png differ diff --git a/docs/editor/images/tasks/configure-task-runner.png b/docs/editor/images/tasks/configure-task-runner.png new file mode 100644 index 0000000000000000000000000000000000000000..b92e009f90ae572e029c5eab9e0d1bda6b0cd5e1 Binary files /dev/null and b/docs/editor/images/tasks/configure-task-runner.png differ diff --git a/docs/editor/images/tasks/configure-tasks.png b/docs/editor/images/tasks/configure-tasks.png new file mode 100644 index 0000000000000000000000000000000000000000..5910f6537eed11eb631bd74e504864fddc290786 Binary files /dev/null and b/docs/editor/images/tasks/configure-tasks.png differ diff --git a/docs/editor/images/tasks/eslint-problem-matcher-selection.png b/docs/editor/images/tasks/eslint-problem-matcher-selection.png new file mode 100644 index 0000000000000000000000000000000000000000..3a42d1e5f9dee0373e5cdd1cd0ce3ea8ca820b3e Binary files /dev/null and b/docs/editor/images/tasks/eslint-problem-matcher-selection.png differ diff --git a/docs/editor/images/tasks/eslint-problem.png b/docs/editor/images/tasks/eslint-problem.png new file mode 100644 index 0000000000000000000000000000000000000000..27df67d7c7bc8c02889f1b36caebccce162e3537 Binary files /dev/null and b/docs/editor/images/tasks/eslint-problem.png differ diff --git a/docs/editor/images/tasks/eslint-starter.png b/docs/editor/images/tasks/eslint-starter.png new file mode 100644 index 0000000000000000000000000000000000000000..a1e951bd2fa9b6d730a11d9ca305a612d1ac5c96 Binary files /dev/null and b/docs/editor/images/tasks/eslint-starter.png differ diff --git a/docs/editor/images/tasks/gulp-auto-detect.png b/docs/editor/images/tasks/gulp-auto-detect.png new file mode 100644 index 0000000000000000000000000000000000000000..9d4060d2ec880aaaec1119a6bda6a72d63f7c83c Binary files /dev/null and b/docs/editor/images/tasks/gulp-auto-detect.png differ diff --git a/docs/editor/images/tasks/gulpautodetect.png b/docs/editor/images/tasks/gulpautodetect.png new file mode 100644 index 0000000000000000000000000000000000000000..6c613a2fe7eb7bd2430d3e97cab78da0c2a8884c Binary files /dev/null and b/docs/editor/images/tasks/gulpautodetect.png differ diff --git a/docs/editor/images/tasks/intellisense.png b/docs/editor/images/tasks/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..30def3bf464786e85e3e99e7f9cfc61c3fccf6af Binary files /dev/null and b/docs/editor/images/tasks/intellisense.png differ diff --git a/docs/editor/images/tasks/problemmatcher.png b/docs/editor/images/tasks/problemmatcher.png new file mode 100644 index 0000000000000000000000000000000000000000..77a7f1ad8ce148a8f39473c8aa3520470f3e1b28 Binary files /dev/null and b/docs/editor/images/tasks/problemmatcher.png differ diff --git a/docs/editor/images/tasks/run-input-example.gif b/docs/editor/images/tasks/run-input-example.gif new file mode 100644 index 0000000000000000000000000000000000000000..6cd3f84db8f41ac8b9e8155d15d7d0c4f0603829 --- /dev/null +++ b/docs/editor/images/tasks/run-input-example.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:79d1811253fafdfc87c4605a1884ee9bc7eacc727da7226eeba484adb2d5a02f +size 415611 diff --git a/docs/editor/images/tasks/tasks-array.png b/docs/editor/images/tasks/tasks-array.png new file mode 100644 index 0000000000000000000000000000000000000000..452fc6260cc95db0b1e2a230872cbf87f7d9673c Binary files /dev/null and b/docs/editor/images/tasks/tasks-array.png differ diff --git a/docs/editor/images/tasks/tasks-command-palette.png b/docs/editor/images/tasks/tasks-command-palette.png new file mode 100644 index 0000000000000000000000000000000000000000..0a210aa64c9e8feecc49c7318b2b25a509088f43 Binary files /dev/null and b/docs/editor/images/tasks/tasks-command-palette.png differ diff --git a/docs/editor/images/tasks/tasks-echoCommand.png b/docs/editor/images/tasks/tasks-echoCommand.png new file mode 100644 index 0000000000000000000000000000000000000000..fa3bd43c92567f9036dfc637fc0822ef84951930 Binary files /dev/null and b/docs/editor/images/tasks/tasks-echoCommand.png differ diff --git a/docs/editor/images/tasks/tasks-intellisense.png b/docs/editor/images/tasks/tasks-intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..fca1da03f2b5adb2752743f7a1b6acba7277f843 Binary files /dev/null and b/docs/editor/images/tasks/tasks-intellisense.png differ diff --git a/docs/editor/images/tasks/tasks_hero.png b/docs/editor/images/tasks/tasks_hero.png new file mode 100644 index 0000000000000000000000000000000000000000..871110f516c5a8cd57bb8e99bca884fc94b8b7ab Binary files /dev/null and b/docs/editor/images/tasks/tasks_hero.png differ diff --git a/docs/editor/images/tasks/typescript-build.png b/docs/editor/images/tasks/typescript-build.png new file mode 100644 index 0000000000000000000000000000000000000000..46644f18190fbe1553c5442379edc9e83e147e70 Binary files /dev/null and b/docs/editor/images/tasks/typescript-build.png differ diff --git a/docs/editor/images/userdefinedsnippets/ajax-snippet.gif b/docs/editor/images/userdefinedsnippets/ajax-snippet.gif new file mode 100644 index 0000000000000000000000000000000000000000..c1bacf7e55e0bda61c6c57c6f1ccc6415f6d45be --- /dev/null +++ b/docs/editor/images/userdefinedsnippets/ajax-snippet.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:599f037bc36052e705e6512650c23752605cf53da714f1a21f13417155032b59 +size 342928 diff --git a/docs/editor/images/userdefinedsnippets/snippet-dropdown.png b/docs/editor/images/userdefinedsnippets/snippet-dropdown.png new file mode 100644 index 0000000000000000000000000000000000000000..580cf16af80656034dbd18cebfe8cc5154a7767e Binary files /dev/null and b/docs/editor/images/userdefinedsnippets/snippet-dropdown.png differ diff --git a/docs/editor/images/userdefinedsnippets/snippets_placeholder.png b/docs/editor/images/userdefinedsnippets/snippets_placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..a2fb97b01d78ac0d66074bb3b42fbb2ce66d98ca Binary files /dev/null and b/docs/editor/images/userdefinedsnippets/snippets_placeholder.png differ diff --git a/docs/editor/images/versioncontrol/GitHub-clone-dialog.png b/docs/editor/images/versioncontrol/GitHub-clone-dialog.png new file mode 100644 index 0000000000000000000000000000000000000000..30ea10bd034b4864760ba538be421ae520f191cf --- /dev/null +++ b/docs/editor/images/versioncontrol/GitHub-clone-dialog.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:28c0aea02f2ffca1fd045576e1efd6377abe1fa94a3c0e89dd72636e7ef8b9ed +size 152563 diff --git a/docs/editor/images/versioncontrol/additional-scm-providers.png b/docs/editor/images/versioncontrol/additional-scm-providers.png new file mode 100644 index 0000000000000000000000000000000000000000..2d86a10916d6c7c2a55d559f3a9aa60febfd4bf8 Binary files /dev/null and b/docs/editor/images/versioncontrol/additional-scm-providers.png differ diff --git a/docs/editor/images/versioncontrol/diff-review-pane.png b/docs/editor/images/versioncontrol/diff-review-pane.png new file mode 100644 index 0000000000000000000000000000000000000000..6206dee8af4597ebbbfc077fba82d751906400af Binary files /dev/null and b/docs/editor/images/versioncontrol/diff-review-pane.png differ diff --git a/docs/editor/images/versioncontrol/diff.png b/docs/editor/images/versioncontrol/diff.png new file mode 100644 index 0000000000000000000000000000000000000000..641704b7e93b139ac9619dcf3319ab641df4e806 Binary files /dev/null and b/docs/editor/images/versioncontrol/diff.png differ diff --git a/docs/editor/images/versioncontrol/git-initialize.png b/docs/editor/images/versioncontrol/git-initialize.png new file mode 100644 index 0000000000000000000000000000000000000000..ccfac458a9b987d5ff4521cecbcc94a7deea6563 Binary files /dev/null and b/docs/editor/images/versioncontrol/git-initialize.png differ diff --git a/docs/editor/images/versioncontrol/git-status-bar-publish.png b/docs/editor/images/versioncontrol/git-status-bar-publish.png new file mode 100644 index 0000000000000000000000000000000000000000..31021f609216f787658140f9b272b805a1614836 Binary files /dev/null and b/docs/editor/images/versioncontrol/git-status-bar-publish.png differ diff --git a/docs/editor/images/versioncontrol/git-status-bar-sync.png b/docs/editor/images/versioncontrol/git-status-bar-sync.png new file mode 100644 index 0000000000000000000000000000000000000000..8b6b7ca0af37d5482dbf3635311d2370a149520d Binary files /dev/null and b/docs/editor/images/versioncontrol/git-status-bar-sync.png differ diff --git a/docs/editor/images/versioncontrol/gitbranches.png b/docs/editor/images/versioncontrol/gitbranches.png new file mode 100644 index 0000000000000000000000000000000000000000..a2071575b288462915727ea8c4c7024af59a9740 Binary files /dev/null and b/docs/editor/images/versioncontrol/gitbranches.png differ diff --git a/docs/editor/images/versioncontrol/gitcommands.png b/docs/editor/images/versioncontrol/gitcommands.png new file mode 100644 index 0000000000000000000000000000000000000000..78bc7e92e80be72265812f9a293cddbc2fe750ea Binary files /dev/null and b/docs/editor/images/versioncontrol/gitcommands.png differ diff --git a/docs/editor/images/versioncontrol/gitconfig.png b/docs/editor/images/versioncontrol/gitconfig.png new file mode 100644 index 0000000000000000000000000000000000000000..14811d6c0f860351ec4e70ef5cf19e0c6492145b Binary files /dev/null and b/docs/editor/images/versioncontrol/gitconfig.png differ diff --git a/docs/editor/images/versioncontrol/merge-conflict.png b/docs/editor/images/versioncontrol/merge-conflict.png new file mode 100644 index 0000000000000000000000000000000000000000..82c68ab7d1380ead197aa1009125211117318963 Binary files /dev/null and b/docs/editor/images/versioncontrol/merge-conflict.png differ diff --git a/docs/editor/images/versioncontrol/overview.png b/docs/editor/images/versioncontrol/overview.png new file mode 100644 index 0000000000000000000000000000000000000000..faa6f5756046d4a0046f5d0785578a6680f71d1c Binary files /dev/null and b/docs/editor/images/versioncontrol/overview.png differ diff --git a/docs/editor/images/versioncontrol/scm-more-actions.png b/docs/editor/images/versioncontrol/scm-more-actions.png new file mode 100644 index 0000000000000000000000000000000000000000..36877b93c18025c5cc3c1ac24127671a506995df Binary files /dev/null and b/docs/editor/images/versioncontrol/scm-more-actions.png differ diff --git a/docs/editor/images/versioncontrol/scm-provider-category.png b/docs/editor/images/versioncontrol/scm-provider-category.png new file mode 100644 index 0000000000000000000000000000000000000000..e825864d2d0e23a1bb39d622abde1020acc2810f Binary files /dev/null and b/docs/editor/images/versioncontrol/scm-provider-category.png differ diff --git a/docs/editor/images/versioncontrol/scm.png b/docs/editor/images/versioncontrol/scm.png new file mode 100644 index 0000000000000000000000000000000000000000..aceb33f90fecbec55179a6400903f77b57592048 --- /dev/null +++ b/docs/editor/images/versioncontrol/scm.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:975a66a07476b28e3587260d3cc27a03e18533224ec6cb04fc1535e3ed35e87a +size 118815 diff --git a/docs/editor/images/versioncontrol/set-repo-URL.png b/docs/editor/images/versioncontrol/set-repo-URL.png new file mode 100644 index 0000000000000000000000000000000000000000..1420cf30c19d5a1f4e41932ad8e5af59e6589e1b Binary files /dev/null and b/docs/editor/images/versioncontrol/set-repo-URL.png differ diff --git a/docs/editor/images/versioncontrol/stage-changes.png b/docs/editor/images/versioncontrol/stage-changes.png new file mode 100644 index 0000000000000000000000000000000000000000..e100d6400b1bf2734395839fff284f2ff78c0794 Binary files /dev/null and b/docs/editor/images/versioncontrol/stage-changes.png differ diff --git a/docs/editor/images/whyvscode/macwinlinux2.png b/docs/editor/images/whyvscode/macwinlinux2.png new file mode 100644 index 0000000000000000000000000000000000000000..42eeb62b5b8883f1028106142da05067b64aef31 Binary files /dev/null and b/docs/editor/images/whyvscode/macwinlinux2.png differ diff --git a/docs/editor/integrated-terminal.md b/docs/editor/integrated-terminal.md new file mode 100644 index 0000000000000000000000000000000000000000..cfc7c3aff0b92be60644794f6d76f658be26d7e5 --- /dev/null +++ b/docs/editor/integrated-terminal.md @@ -0,0 +1,389 @@ +--- +Order: 9 +Area: editor +TOCTitle: Integrated Terminal +ContentId: 7B4DC928-2414-4FC7-9C76-E4A13D6675FE +PageTitle: Integrated Terminal in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code has an integrated terminal so you can work in the shell of your choice without leaving the editor. +--- +# Integrated Terminal + +In Visual Studio Code, you can open an integrated terminal, initially starting at the root of your workspace. This can be convenient as you don't have to switch windows or alter the state of an existing terminal to perform a quick command-line task. + +To open the terminal: + +* Use the `kb(workbench.action.terminal.toggleTerminal)` keyboard shortcut with the backtick character. +* Use the **View** > **Terminal** menu command. +* From the **Command Palette** (`kb(workbench.action.showCommands)`), use the **View: Toggle Integrated Terminal** command. + +![Terminal](images/integrated-terminal/integrated-terminal.png) + +> **Note:** You can still open an external shell with the `kb(workbench.action.terminal.openNativeConsole)` keyboard shortcut if you prefer to work outside VS Code. + +## Managing multiple terminals + +You can create multiple terminals open to different locations and easily navigate between them. Terminal instances can be added by clicking the plus icon on the top-right of the **TERMINAL** panel or by triggering the `kb(workbench.action.terminal.new)` command. This action creates another entry in the drop-down list that can be used to switch between them. + +![Multiple Terminals](images/integrated-terminal/terminal-multiple-instances.png) + +Remove terminal instances by pressing the trash can button. + +>**Tip:** If you use multiple terminals extensively, you can add key bindings for the `focusNext`, `focusPrevious` and `kill` commands outlined in the [Key Bindings section](/docs/editor/integrated-terminal.md#terminal-key-bindings) to allow navigation between them using only the keyboard. + +### Terminal Splitting + +You can also split the terminal by triggering the `kb(workbench.action.terminal.split)` command or via the right click context menu. + +![Split terminals](images/integrated-terminal/terminal-split-pane.png) + +When focusing a split terminal pane, you can move focus and resize using one of the following commands: + +Key|Command +---|--- +`kb(workbench.action.terminal.focusPreviousPane)` | Focus Previous Pane +`kb(workbench.action.terminal.focusNextPane)` | Focus Next Pane +`kb(workbench.action.terminal.resizePaneLeft)` | Resize Pane Left +`kb(workbench.action.terminal.resizePaneRight)` | Resize Pane Right +`kb(workbench.action.terminal.resizePaneUp)` | Resize Pane Up +`kb(workbench.action.terminal.resizePaneDown)` | Resize Pane Down + +## Configuration + +The shell used defaults to `$SHELL` on Linux and macOS, PowerShell on Windows 10 and cmd.exe on earlier versions of Windows. These can be overridden manually by setting `terminal.integrated.shell.*` in user [settings](/docs/getstarted/settings.md). Arguments can be passed to the terminal shell using the `terminal.integrated.shellArgs.*` user settings. + +>**Note:** For [enhanced security](/docs/getstarted/settings.md#settings-and-security), such settings can only be defined in user settings and not at workspace scope. + +### Windows + +Correctly configuring your shell on Windows is a matter of locating the right executable and updating the setting. Below are a list of common shell executables and their default locations: + +```json +// Command Prompt +"terminal.integrated.shell.windows": "C:\\Windows\\System32\\cmd.exe" +// PowerShell +"terminal.integrated.shell.windows": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe" +// Git Bash +"terminal.integrated.shell.windows": "C:\\Program Files\\Git\\bin\\bash.exe" +// Bash on Ubuntu (on Windows) +"terminal.integrated.shell.windows": "C:\\Windows\\System32\\bash.exe" +``` + +There is also the convenience command, **Terminal: Select Default Shell** that can be accessed through the Command Palette, which can detect and set this for you. + +>**Note:** To be used as an integrated terminal, the shell executable must be a console application so that `stdin/stdout/stderr` can be redirected. + +>**Tip:** The integrated terminal shell is running with the permissions of VS Code. If you need to run a shell command with elevated (administrator) or different permissions, you can use platform utilities such as `runas.exe` within a terminal. + +### Shell arguments + +You can pass arguments to the shell when it is launched. + +For example, to enable running bash as a login shell (which runs `.bash_profile`), pass in the `-l` argument (with double quotes): + +```json +// Linux +"terminal.integrated.shellArgs.linux": ["-l"] +``` + +## Terminal display settings + +You can customize the integrated terminal font and line height with the following settings: + +* `terminal.integrated.fontFamily` +* `terminal.integrated.fontSize` +* `terminal.integrated.fontWeight` +* `terminal.integrated.fontWeightBold` +* `terminal.integrated.lineHeight` + +## Terminal keybindings + +The **View: Toggle Integrated Terminal** command is bound to `kb(workbench.action.terminal.toggleTerminal)` to quickly toggle the integrated terminal panel in and out of view. + +Below are the keyboard shortcuts to quickly navigate within the integrated terminal: + +Key|Command +---|--- +`kb(workbench.action.terminal.toggleTerminal)`|Show integrated terminal +`kb(workbench.action.terminal.new)`|Create new terminal +`kb(workbench.action.terminal.scrollUp)`|Scroll up +`kb(workbench.action.terminal.scrollDown)`|Scroll down +`kb(workbench.action.terminal.scrollUpPage)`|Scroll page up +`kb(workbench.action.terminal.scrollDownPage)`|Scroll page down +`kb(workbench.action.terminal.scrollToTop)`|Scroll to top +`kb(workbench.action.terminal.scrollToBottom)`|Scroll to bottom +`kb(workbench.action.terminal.clear)`|Clear the terminal + +Other terminal commands are available and can be bound to your preferred keyboard shortcuts. + +They are: + +* `workbench.action.terminal.focus`: Focus the terminal. This is like toggle but focuses the terminal instead of hiding it, if it is visible. +* `workbench.action.terminal.focusNext`: Focuses the next terminal instance. +* `workbench.action.terminal.focusPrevious`: Focuses the previous terminal instance. +* `workbench.action.terminal.focusAtIndexN`: Focuses the terminal at index N (N=1-9) +* `workbench.action.terminal.kill`: Remove the current terminal instance. +* `workbench.action.terminal.runSelectedText`: Run the selected text in the terminal instance. +* `workbench.action.terminal.runActiveFile`: Run the active file in the terminal instance. + +### Copy & Paste + +The keybindings for copy and paste follow platform standards: + +* Linux: `kbstyle(Ctrl+Shift+C)` and `kbstyle(Ctrl+Shift+V)` +* macOS: `kbstyle(Cmd+C)` and `kbstyle(Cmd+V)` +* Windows: `kbstyle(Ctrl+C)` and `kbstyle(Ctrl+V)` + +### Right click behavior + +The right click behavior differs based on the platform: + +* Linux: Show the context menu. +* macOS: Select the word under the cursor and show the context menu. +* Windows: Copy and drop selection if there is a selection, otherwise paste. + +This can be configured using the `terminal.integrated.rightClickBehavior` setting. + +### Forcing key bindings to pass through the terminal + +While focus is in the integrated terminal, many key bindings will not work as the keystrokes are passed to and consumed by the terminal itself. There is a hardcoded list of commands, which skip being processed by the shell and instead get sent to the VS Code keybinding system. You can customize this list with the `terminal.integrated.commandsToSkipShell` setting. Commands can be added to this list by adding the command name to the list, and removed by adding the command name to the list prefixed with a `-`. + +```js +{ + "terminal.integrated.commandsToSkipShell": [ + // Ensure the toggle sidebar visibility keybinding skips the shell + "workbench.action.toggleSidebarVisibility" + // Send quick open's keybinding to the shell + "-workbench.action.quickOpen", + ] +} +``` + +Look at the setting details to see the complete list of default commands. + +### Find + +The Integrated Terminal has basic find functionality which can be triggered with `kb(workbench.action.terminal.focusFindWidget)`. + +If you want `kbstyle(Ctrl+F)` to go to the shell instead of launching the Find widget on Linux and Windows, you will need to remove the keybinding like so: + +```js +// Windows/Linux +{ "key": "ctrl+f", "command": "-workbench.action.terminal.focusFindWidget", + "when": "terminalFocus" }, +// macOS +{ "key": "cmd+f", "command": "-workbench.action.terminal.focusFindWidget", + "when": "terminalFocus" }, +``` + +## Run Selected Text + +To use the `runSelectedText` command, select text in an editor and run the command **Terminal: Run Selected Text in Active Terminal** via the **Command Palette** (`kb(workbench.action.showCommands)`): + +![Run selected text](images/integrated-terminal/terminal_run_selected.png) + +The terminal will attempt to run the selected text. + +![Run selected text result](images/integrated-terminal/terminal_run_selected_result.png) + +If no text is selected in the active editor, the line that the cursor is on is run in the terminal. + +## Send text from a keybinding + +The `workbench.action.terminal.sendSequence` command can be used to send a specific sequence of text to the terminal, including escape sequences. This enables things like sending arrow keys, enter, cursor moves, etc. The example below shows the sorts of things you can achieve with this feature, it jumps over the word to the left of the cursor (Ctrl+Left arrow) and presses backspace: + +```json +{ + "key": "ctrl+u", + "command": "workbench.action.terminal.sendSequence", + "args": { "text": "\u001b[1;5D\u007f" } +} +``` + +This feature supports [variable substitution](/docs/editor/variables-reference.md). + +Note that the command only works with the `\u0000` format for using characters via their character code (not `\x00`). You can read more about these hex code and the sequences terminals work with on the following resources: + +- [XTerm Control Sequences](http://invisible-island.net/xterm/ctlseqs/ctlseqs.html) +- [List of C0 and C1 control codes](https://github.com/xtermjs/xterm.js/blob/0e45909c7e79c83452493d2cd46d99c0a0bb585f/src/common/data/EscapeSequences.ts) + +## Rename terminal sessions + +Integrated Terminal sessions can now be renamed using the **Terminal: Rename** (`workbench.action.terminal.rename`) command. The new name will be displayed in the terminal selection drop-down. + +## Open at a specific folder + +By default, the terminal will open at the folder that is opened in the Explorer. The `terminal.integrated.cwd` setting allows specifying a custom path to open instead: + +```json +{ + "terminal.integrated.cwd": "/home/user" +} +``` + +Split terminals on Windows will start in the directory that the parent terminal started with. On MacOS and Linux, split terminals will inherit the current working directory of the parent terminal. This behavior can be changed using the `terminal.integrated.splitCwd` setting: + +```json +{ + "terminal.integrated.splitCwd": "workspaceRoot" +} +``` + +There are also extensions available that give more options such as [Terminal Here](https://marketplace.visualstudio.com/items?itemName=Tyriar.vscode-terminal-here). + +## Changing how the terminal is rendered + +By default, the integrated terminal will render using multiple `` elements which are better tuned than the DOM for rendering interactive text that changes often. However, Electron/Chromium are slower at rendering to canvas on some environments so VS Code also provides a fallback DOM-renderer experience. VS Code will try to detect slow performance and give you the option to change via a notification. You can also change the rendering directly by setting `terminal.integrated.rendererType` in your user or workspace [settings](/docs/getstarted/settings.md). + +```js +{ + "terminal.integrated.rendererType": "dom" +} +``` + +Something else that might improve performance is to ignore Chromium's GPU blacklist by launching VS Code with `code --ignore-gpu-blacklist`. + +## Next steps + +The basics of the terminal have been covered in this document, read on to find out more about: + +* [Tasks](/docs/editor/tasks.md) - Tasks let you integrate with external tools and leverage the terminal heavily. +* [Mastering VS Code's Terminal](https://www.growingwiththeweb.com/2017/03/mastering-vscodes-terminal.html) - An external blog with plenty of power user tips for the terminal. +* Explore the rest of the terminal commands by browsing your keybindings.json file within VS Code. + +## Common questions + +### Why is VS Code shortcut X not working when the terminal has focus? + +Currently the terminal consumes many key bindings, preventing Visual Studio Code from reacting to them. Some examples are `kbstyle(F1)` to open the **Command Palette** and `kbstyle(Ctrl+P)` for **Quick Open** on Linux and Windows. This is necessary as various terminal programs and/or shells may respond to these key bindings themselves. There are plans to explore a blacklist that would prevent certain key bindings from being handled by the terminal (see [#7269](https://github.com/Microsoft/vscode/issues/7269)). + +### Integrated terminal exited with code 1 on Windows 10 + +This can happen if you run VS Code in compatibility mode which may be turned on automatically if you have upgraded Windows. You can change this by right-clicking the executable and selecting properties, then uncheck "Run this program in compatibility mode" in the compatibility tab. + +### Can I use Cmder's shell with the terminal on Windows? + +Yes, to use the [Cmder](http://cmder.net/) shell in VS Code, you need to add the following settings to your `settings.json` file: + +```json +"terminal.integrated.shell.windows": "C:\\WINDOWS\\System32\\cmd.exe", +"terminal.integrated.shellArgs.windows": ["/K", "C:\\cmder\\vendor\\init.bat"] +``` + +You may refer to [Cmder's wiki](https://github.com/cmderdev/cmder/wiki/Seamless-VS-Code-Integration) for more information. + +### Can I use Cygwin's shell with the terminal on Windows? + +Yes, to use the [Cygwin](http://cygwin.com/) shell, you will first need to install the chere package and then add the following settings to your `settings.json` file: + +```json +"terminal.integrated.shell.windows": "C:\\Cygwin\\bin\\bash.exe", +"terminal.integrated.shellArgs.windows": ["/bin/xhere", "/bin/bash"] +``` + +### Powershell on macOS is complaining about a "-l" argument, how do I fix it? + +When configuring the integrated terminal to use Powershell on macOS you may hit [this error](https://github.com/Microsoft/vscode/issues/33022) complaining about a `"-l"` argument. To fix this you will need to override the shell args setting as it defaults to `["-l"]` to run login shells by default (for bash/zsh/etc.). + +```js +"terminal.integrated.shellArgs.osx": [] +``` + +### How can I change my default Windows terminal back to PowerShell? + +If you want to put the default Integrated Terminal shell back to the default (PowerShell on Windows), you can remove the shell override from your User [Settings](/docs/getstarted/settings.md) (`kb(workbench.action.openSettings)`). + +For example, if you have set your default terminal to bash, you will find `terminal.integrated.shell.windows` in your `settings.json` pointing to your bash location. + +```json +"terminal.integrated.shell.windows": "C:\\WINDOWS\\System32\\bash.exe", +``` + +Remove the entry to use the built-in VS Code default or set it to another shell executable path. + +### Why is the terminal not working when running the 32-bit Windows client on 64-bit Windows? + +The easy fix for this is to use the 64-bit version. If you must use the 32-bit version you need to use the `sysnative` path when configuring your paths instead of `System32`: + +```json +"terminal.integrated.shell.windows": "C:\\WINDOWS\\sysnative\\cmd.exe", +``` + +### Why is Cmd+k/Ctrl+k not clearing the terminal? + +Normally `kbstyle(Cmd+k)`/`kbstyle(Ctrl+k)` clears the terminal on macOS/Windows, but this can stop working when chord keybindings are added either by the user or extensions. The `kbstyle(Cmd+k)`/`kbstyle(Ctrl+k)` keybindings rely on the VS Code keybinding priority system which defines which keybinding is active at any given time (user > extension > default). In order to fix this, you need to redefine your user keybinding which will have priority, preferably at the bottom of your user `keybindings.json` file: + +macOS: + +```json +{ "key": "cmd+k", "command": "workbench.action.terminal.clear", + "when": "terminalFocus" }, +``` + +Windows: + +```json +{ "key": "ctrl+k", "command": "workbench.action.terminal.clear", + "when": "terminalFocus" }, +``` + +### Why is nvm complaining about a prefix option when the Integrated Terminal is launched? + +nvm (Node Version Manager) users often see this error for the first time inside VS Code's Integrated Terminal: + +```bash +nvm is not compatible with the npm config "prefix" option: currently set to "/usr/local" +Run `npm config delete prefix` or `nvm use --delete-prefix v8.9.1 --silent` to unset it +``` + +This is mostly a macOS problem and does not happen in external terminals. The typical reasons for this are the following: + +* `npm` was globally installed using another instance of `node` which is somewhere in your path (such as `/usr/local/bin/npm`). +* In order to get the development tools on the `$PATH`, VS Code will launch a bash login shell on start up. This means that your `~/.bash_profile` has already run and when an Integrated Terminal launches, it will run **another** login shell, reordering the `$PATH` potentially in unexpected ways. + +To resolve this issue, you need to track down where the old `npm` is installed and remove both it and its out of date node_modules. You can do this by finding the `nvm` initialization script and running `which npm` before it runs, which should print the path when you launch a new terminal. + +Once you have the path to npm, you can find the old node_modules by resolving the symlink by running a command something like this: + +```bash +ls -la /usr/local/bin | grep npm +``` + +This will give you the resolved path at the end: + +```bash +... npm -> ../lib/node_modules/npm/bin/npm-cli.js +``` + +From there, removing the files and relaunching VS Code should fix the issue: + +```bash +rm -R /usr/local/bin/npm /usr/local/lib/node_modules/npm/bin/npm-cli.js +``` + +### Can I use Powerline fonts in the Integrated Terminal? + +Yes, you can specify [Powerline](https://powerline.readthedocs.io) fonts with the `terminal.integrated.fontFamily` [setting](/docs/getstarted/settings.md). + +```json +"terminal.integrated.fontFamily": "Meslo LG M DZ for Powerline" +``` + +Note that you want to specify the font family, not an individual font like **Meslo LG M DZ Regular for Powerline** where **Regular** is the specific font name. + +### How do I configure zsh on macOS to jump words with Ctrl+Left/Right arrow? + +By default, `kbstyle(Ctrl+Left/Right)` arrow will jump words in bash. You can configure the same for zsh by adding these keybindings: + +```json +{ + "key": "ctrl+left", + "command": "workbench.action.terminal.sendSequence", + "args": { "text": "\u001bb" } +}, +{ + "key": "ctrl+right", + "command": "workbench.action.terminal.sendSequence", + "args": { "text": "\u001bf" } +} +``` diff --git a/docs/editor/intellisense.md b/docs/editor/intellisense.md new file mode 100644 index 0000000000000000000000000000000000000000..1be8548b22319f4ea662a6bf84c57cd07f9a2a93 --- /dev/null +++ b/docs/editor/intellisense.md @@ -0,0 +1,209 @@ +--- +Order: 4 +Area: editor +TOCTitle: IntelliSense +ContentId: 80f4fa1e-d4c5-42cf-8b12-4b8e88c41c3e +PageTitle: IntelliSense in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Learn about Visual Studio Code IntelliSense (intelligent code completion). +--- +# IntelliSense + +IntelliSense is a general term for a variety of code editing features including: code completion, parameter info, quick info, and member lists. IntelliSense features are sometimes called by other names such as "code completion", "content assist", and "code hinting." + +![IntelliSense demo](images/intellisense/intellisense.gif) + +## IntelliSense for your programming language + +Visual Studio Code IntelliSense is provided for JavaScript, TypeScript, JSON, HTML, CSS, SCSS, and Less out of the box. VS Code supports word based completions for any programming language but can also be configured to have richer IntelliSense by installing a language extension. + +Below are the most popular language extensions in the [Marketplace](https://marketplace.visualstudio.com/vscode). Click on an extension tile below to read the description and reviews to decide which extension is best for you. + +
+ +## IntelliSense features + +VS Code IntelliSense features are powered by a language service. A language service provides intelligent code completions based on language semantics and an analysis of your source code. If a language service knows possible completions, the IntelliSense suggestions will pop up as you type. If you continue typing characters, the list of members (variables, methods, etc.) is filtered to include only members containing your typed characters. Pressing `kbstyle(Tab)` or `kbstyle(Enter)` will insert the selected member. + +You can trigger IntelliSense in any editor window by typing `kb(editor.action.triggerSuggest)` or by typing a trigger character (such as the dot character (`kbstyle(.)`) in JavaScript). + +![intellisense in package json](images/intellisense/intellisense_packagejson.gif) + +> **Tip:** The suggestions widget supports CamelCase filtering meaning you can type the letters which are upper cased in a method name to limit the suggestions. For example, "cra" will quickly bring up "createApplication". + +If you prefer, you can turn off IntelliSense while you type. See [Customizing IntelliSense](/docs/editor/intellisense.md#customizing-intellisense) below to learn how to disable or customize VS Code's IntelliSense features. + +As provided by the language service, you can see **quick info** for each method by either pressing `kb(toggleSuggestionDetails)` or clicking the info icon. The accompanying documentation for the method will now expand to the side. The expanded documentation will stay so and will update as you navigate the list. You can close this by pressing `kb(toggleSuggestionDetails)` again or by clicking on the close icon. + +![quick info](images/intellisense/intellisense_docs.gif) + +After choosing a method you are provided with **parameter info**. + +![parameter info](images/intellisense/paramater_info.png) + +When applicable, a language service will surface the underlying types in the quick info and method signatures. In the image above, you can see several `any` types. Because JavaScript is dynamic and doesn't need or enforce types, `any` suggests that the variable can be of any type. + +## Types of completions + +The JavaScript code below illustrates IntelliSense completions. IntelliSense gives both inferred proposals and the global identifiers of the project. The inferred symbols are presented first, followed by the global identifiers (shown by the document icon). + +![intellisense icons](images/intellisense/intellisense_icons.png) + +VS Code IntelliSense offers different types of completions, including language server suggestions, snippets, and simple word based textual completions. + +| | | +| ----- | ------- | +| ![method icon](images/intellisense/Method_16x.svg) | Methods, Functions and Constructors | +| ![variable icon](images/intellisense/Field_16x.svg) | Variables and Fields | +| ![class](images/intellisense/Class_16x.svg) | Classes | +| ![interface](images/intellisense/Interface_16x.svg) | Interfaces | +| ![module](images/intellisense/Namespace_16x.svg) | Modules | +| ![property](images/intellisense/Property_16x.svg) | Properties and Attributes | +| ![enumeration icon](images/intellisense/EnumItem_16x.svg) | Values and Enumerations | +| ![color](images/intellisense/Enumerator_16x.svg) | References | +| ![keyword](images/intellisense/IntelliSenseKeyword_16x.svg) | Keywords | +| ![global identifiers](images/intellisense/Document_16x.svg) | Global Identifiers | +| ![color](images/intellisense/ColorPalette_16x.svg) | Colors | +| ![unit](images/intellisense/Ruler_16x.svg) | Unit | +| ![a square with ellipses forming the bottom show snippet prefix](images/intellisense/Snippet_16x.svg) | Snippet Prefixes | +| ![a square with letters abc word completion](images/intellisense/String_16x.svg) | Words | +| ![Miscellaneous](images/intellisense/Misc_16x.svg) | Miscellaneous | + +## Customizing IntelliSense + +You can customize your IntelliSense experience in settings and key bindings. + +### Settings + +The settings shown below are the default settings. You can change these settings in your `settings.json` file as described in [User and Workspace Settings](/docs/getstarted/settings.md). + +```javascript +{ + // Controls if quick suggestions should show up while typing + "editor.quickSuggestions": { + "other": true, + "comments": false, + "strings": false + }, + + // Controls if suggestions should be accepted on 'Enter' - in addition to 'Tab'. Helps to avoid ambiguity between inserting new lines or accepting suggestions. The value 'smart' means only accept a suggestion with Enter when it makes a textual change + "editor.acceptSuggestionOnEnter": "on", + + // Controls the delay in ms after which quick suggestions will show up. + "editor.quickSuggestionsDelay": 10, + + // Controls if suggestions should automatically show up when typing trigger characters + "editor.suggestOnTriggerCharacters": true, + + // Controls if pressing tab inserts the best suggestion and if tab cycles through other suggestions + "editor.tabCompletion": "on", + + // Controls whether sorting favours words that appear close to the cursor + "editor.suggest.localityBonus": true, + + // Controls how suggestions are pre-selected when showing the suggest list + "editor.suggestSelection": "recentlyUsed", + + // Enable word based suggestions + "editor.wordBasedSuggestions": true, + + // Enable parameter hints + "editor.parameterHints": true, +} +``` + +### Tab Completion + +The editor supports "tab completion" which inserts the best matching completion when pressing `kb(insertBestCompletion)`. This works regardless of the suggest widget showing or not. Also, pressing `kb(insertNextSuggestion)` after inserting a suggestions will insert the next best suggestion. + +![Tab Completion](images/intellisense/tabCompletion.gif) + +By default, tab completion is disabled. Use the `editor.tabCompletion` setting to enable it. These values exist: + +* `off` - (default) Tab completion is disabled. +* `on` - Tab completion is enabled for all suggestions and repeated invocations insert the next best suggestion. +* `onlySnippets` - Tab completion only inserts static snippets which prefix match the current line prefix. + +### Locality Bonus + +Sorting of suggestions depends on extension information and on how well they match the current word you are typing. In addition, you can ask the editor to boost suggestions that appear closer to the cursor position, using the `editor.suggest.localityBonus` setting. + +![Sorted By Locality](images/intellisense/localitybonus.png) + +In above images you can see that `count`, `context`, and `colocated` are sorted based on the scopes in which they appear (loop, function, file). + +### Suggestion selection + +By default, VS Code pre-selects the previously used suggestion in the suggestion list. This is very useful as you can quickly insert the same completion multiple times. If you'd like different behavior, for example, always select the top item in the suggestion list, you can use the `editor.suggestSelection` setting. + +The available `editor.suggestSelection` values are: + +* `first` - Always select the top list item. +* `recentlyUsed` - (default) The previously used item is selected unless a prefix (type to select) selects a different item. +* `recentlyUsedByPrefix` - Select items based on previous prefixes that have completed those suggestions. + +"Type to select" means that the current prefix (roughly the text left of the cursor) is used to filter and sort suggestions. When this happens and when its result differs from the result of `recentlyUsed` it will be given precedence. + +When using the last option, `recentlyUsedByPrefix`, VS Code remembers which item was selected for a specific prefix (partial text). For example, if you typed `co` and then selected `console`, the next time you typed `co`, the suggestion `console` would be pre-selected. This lets you quickly map various prefixes to different suggestions, for example `co` -> `console` and `con` -> `const`. + +### Snippets in suggestions + +By default, VS Code shows snippets and completion proposals in one widget. You can control the behavior with the `editor.snippetSuggestions` setting. To remove snippets from the suggestions widget, set the value to `"none"`. If you'd like to see snippets, you can specify the order relative to suggestions; at the top (`"top"`), at the bottom (`"bottom"`), or inline ordered alphabetically (`"inline"`). The default is `"inline"`. + + +### Key bindings + +The key bindings shown below are the default key bindings. You can change these in your `keybindings.json` file as described in [Key Bindings](/docs/getstarted/keybindings.md). + +> **Note:** There are many more key bindings relating to IntelliSense. Open the **Default Keyboard Shortcuts** (**File** > **Preferences** > **Keyboard Shortcuts**) and search for "suggest". + +```json +[ + { + "key": "ctrl+space", + "command": "editor.action.triggerSuggest", + "when": "editorHasCompletionItemProvider && editorTextFocus && !editorReadonly" + }, + { + "key": "ctrl+space", + "command": "toggleSuggestionDetails", + "when": "editorTextFocus && suggestWidgetVisible" + }, + { + "key": "ctrl+alt+space", + "command": "toggleSuggestionFocus", + "when": "editorTextFocus && suggestWidgetVisible" + } +] +``` + +## Troubleshooting + +If you find IntelliSense has stopped working, the language service may not be running. Try restarting VS Code and this should solve the issue. If you are still missing IntelliSense features after installing a language extension, open an issue in the repository of the language extension. + +> **Tip:** For configuring and troubleshooting JavaScript IntelliSense see [here](/docs/languages/javascript.md#intellisense). + +A particular language extension may not support all the VS Code IntelliSense features. Review the extension's README to find out what is supported. If you think there are issues with a language extension, you can usually find the issue repository for an extension through the [Marketplace](https://marketplace.visualstudio.com/vscode). Navigate to the extension's detail page and click the `Support` link. + +## Next steps + +IntelliSense is just one of VS Code's powerful features. Read on to learn more: + +* [JavaScript](/docs/languages/javascript.md) - Get the most out of your JavaScript development, including configuring IntelliSense. +* [Node.js](/docs/nodejs/nodejs-tutorial.md) - See an example of IntelliSense in action in the Node.js walkthrough. +* [Debugging](/docs/editor/debugging.md) - Learn how to set up debugging for your application. + +## Common questions + +### Why am I not getting any suggestions? + +![image of IntelliSense not working](images/intellisense/intellisense_error.png) + +This can be caused by a variety of reasons. First, try restarting VS Code. If the problem persists, consult the language extension's documentation. For JavaScript specific troubleshooting, please see the [JavaScript language topic](/docs/languages/javascript.md#intellisense). + +### Why am I not seeing method and variable suggestions? + +![image of IntelliSense showing no useful suggestions](images/intellisense/missing_typings.png) + +This issue is caused by missing type declaration (typings) files in JavaScript. You can check if a type declaration file package is available for a specific library by using the [TypeSearch](https://microsoft.github.io/TypeSearch) site. There is more information about this issue in the [JavaScript language topic](/docs/languages/javascript.md#intellisense). For other languages, please consult the extension's documentation. + diff --git a/docs/editor/multi-root-workspaces.md b/docs/editor/multi-root-workspaces.md new file mode 100644 index 0000000000000000000000000000000000000000..6d3723dfffaf877a829c16e0603369d00ff9797c --- /dev/null +++ b/docs/editor/multi-root-workspaces.md @@ -0,0 +1,336 @@ +--- +Order: 10 +Area: editor +TOCTitle: Multi-root Workspaces +ContentId: 8d55f6b8-977f-4c26-a888-f3d8d982dd2d +PageTitle: Multi-root Workspaces in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: You can open and work on multiple project folders in Visual Studio Code with multi-root workspaces. +--- +# Multi-root Workspaces + +You can work with multiple project folders in Visual Studio Code with multi-root workspaces. This can be very helpful when you are working on several related projects at one time. For example, you might have a repository with a product's documentation which you like to keep current when you update the product source code. + +![multi-root hero](images/multi-root-workspaces/hero.png) + +## Adding folders + +It is easy to add another folder to your existing workspace. There are several gestures for adding folders: + +### Add Folder to Workspace... + +The **File** > **Add Folder to Workspace** command brings up an Open Folder dialog to select the new folder. + +![Add Root Folder](images/multi-root-workspaces/add-root-folder.png) + +Once a root folder is added, the Explorer will show the new folder as a root in the File Explorer. You can right click on any of the root folders and use the context menu to add or remove folders. + +![Remove Root Folder](images/multi-root-workspaces/explorer-context.png) + +The File Explorer should work and behave as before. You can move files between root folders and use any of the typical file operation actions provided in the context menu and the Explorer view. + +Settings like `files.exclude` are supported for each root folder if configured and across all folders if configured as global user setting. + +### Drag and drop + +You can use drag and drop to add folders to a workspace. Drag a folder to the File Explorer to add it to the current workspace. You can even select and drag multiple folders. + +>**Note**: Dropping a single folder into the editor region of VS Code will still open the folder in single folder mode. If you drag and drop multiple folders into the editor region, a new multi-root workspace will be created. + +You can also use drag and drop to reorder folders in the workspace. + +### Multiple selection native file open dialogs + +Opening multiple folders with your platform's native file open dialog will create a multi-root workspace. + +### command line --add + +Add a folder or multiple folders to the last active VS Code instance for a multi-root workspace. + +```bash + code --add vscode vscode-docs +``` + +### Removing folders + +You can remove a folder from a Workspace with the **Remove Folder from Workspace** context menu command. + +## Workspace file + +When you add multiple folders, they are initially placed in a Workspace titled **UNTITLED WORKSPACE** and that name will remain until you save the workspace. You do not need to save a Workspace until you want to have it in a permanent location, for example, on your Desktop. Untitled Workspaces are present as long as the VS Code instance they are using is open. Once you completely close an instance with an untitled workspace, you will be asked to save it if you plan to open it again in the future: + +![save workspace dialog](images/multi-root-workspaces/save-workspace.png) + +When you save your workspace, it will create a `.code-workspace` file and the file name will be displayed in the File Explorer. + +### Save Workspace As... + +If you want to move your Workspace file to a new location, you can use the **File** > **Save Workspace As** command which will automatically set the correct folder paths relative to the new Workspace file location. + +### Opening workspace files + +To reopen a Workspace, you can: + +* Double click the `.code-workspace` file in your platform's Explorer. +* Use the **File** > **Open Workspace** command and select the Workspace file. +* Select the Workspace from the **File** > **Open Recent** (`kb(workbench.action.openRecent)`) list. + * Workspaces have a **(Workspace)** suffix to differentiate them from folders. + +![open recent workspace list](images/multi-root-workspaces/open-recent.png) + +Just like **Close Folder** when a single folder is open in VS Code, there is a **Close Workspace** (`kb(workbench.action.closeFolder)`) command to close the active Workspace. + +### Workspace file schema + +The schema of `.code-workspace` is fairly straightforward. You have an array of folders with either absolute or relative paths. Relative paths are better when you want to share Workspace files. + +You can override the display name of your folders with the `name` attribute for a clearer display in the Explorer. For example, you could more clearly name your project folders such as 'Product' and 'Documentation': + +```json +{ + "folders": [ + { + // Source code + "name": "Product", + "path": "vscode" + }, + { + // Docs and release notes + "name": "Documentation", + "path": "vscode-docs" + }, + { + // Yeoman extension generator + "name": "Extension generator", + "path": "vscode-generator-code" + } + ] +} +``` + +which will result in the following Explorer display: + +![named folders](images/multi-root-workspaces/named-folders.png) + +As you can see from the example above, you can add comments to your Workspace files. + +The Workspace file can also contain Workspace [global settings](#settings) under `settings` and [extension recommendations](#extensions) under `extensions` which we will discuss below. + +![workspace file schema](images/multi-root-workspaces/workspace-file-schema.png) + +## General UI + +### Editor + +There are only a few changes to the VS Code UI when you are using multi-root workspaces, primarily to disambiguate files between folders. For example, if there is a name collision between files in multiple folders, VS Code will include the folder name in tabbed headers. + +![tabbed headers](images/multi-root-workspaces/tabbed-headers.png) + +If you'd always like to see the folder displayed in the tabbed header, you can use the `workbench.editor.labelFormat` [setting](/docs/getstarted/settings.md) "medium" or "long" values to show the folder or full paths. + +```json +"workbench.editor.labelFormat": "medium" +``` + +VS Code UI such as the **OPEN EDITORS** or **Quick Open** (`kb(workbench.action.quickOpen)`) list include the folder name. + +![quick pick has folder name](images/multi-root-workspaces/quick-open-list.png) + +If you are using an [Icon Theme](/docs/getstarted/themes.md#icon-themes) and the active theme supports it, you will see a special Workspace icon. + +Below you can see the Workspace icons from the built-in **Minimal (Visual Studio Code)** icon theme: + +![custom workspace icon](images/multi-root-workspaces/workspace-icon.png) + +### Search + +VS Code features like global search work across all folders and group the search results by folder. + +![multi-root search results](images/multi-root-workspaces/search.png) + +When you have a multi-root workspace open, you can choose to search in a single root folder by using the `./` syntax in the **files to include** box. For example, if you enter `./project1/**/*.txt`, that will search for all `.txt` files under the `project1/` root folder. + +## Settings + +With multiple root folders in one workspace, it is possible to have a `.vscode` folder in each root folder defining the settings that should apply for that folder. To avoid setting collisions, only resource (file, folder) settings are applied when using a multi-root workspace. Settings which affect the entire editor (for example, UI layout) are ignored. For example, two projects cannot both set the zoom level. + +User settings are supported as with single folder projects and you can also set global Workspace settings which will apply to all folders in your multi-root Workspace. Global Workspace settings will be stored in your `.code-workspace` file. + +```json +{ + "folders": [ + { + "path": "vscode" + }, + { + "path": "vscode-docs" + }, + { + "path": "vscode-generator-code" + } + ], + "settings": { + "window.zoomLevel": 1, + "files.autoSave": "afterDelay" + } +} +``` + +When you go from a single folder instance to multiple folders, VS Code will add the appropriate editor-wide settings from the first folder to the new global Workspace settings. + +You can easily review and modify the different settings files through the Settings editor. The Settings editor tabs let you select your User settings, global Workspace settings, and individual folder settings. + +![settings drop-down](images/multi-root-workspaces/settings-dropdown.png) + +You can also open specific settings files with the commands: + +* **Preferences: Open User Settings** - Open your global User settings +* **Preferences: Open Workspace Settings** - Open the settings section of your Workspace file. +* **Preferences: Open Folder Settings** - Open the settings for the active folder. + +Global Workspace settings override User settings and folder settings can override Workspace or User settings. + +### Unsupported folder settings + +Unsupported editor-wide folder settings will be shown as grayed out in your folder settings and are filtered out of the **DEFAULT FOLDER SETTINGS** list. You will also see an information icon in front of the setting. + +![unsupported setting information](images/multi-root-workspaces/unsupported-setting-info.png) + +## Debugging + +With multi-root workspaces, VS Code searches across all folders for `launch.json` debug configuration files and displays them with the folder name as a suffix. Additionally VS Code will also display launch configurations defined in the workspace configuration file. + +![debugging drop-down](images/multi-root-workspaces/debugging-dropdown.png) + +The example above shows the debugging configurations for the [TSLint extension](https://marketplace.visualstudio.com/items?itemName=eg2.tslint). There is a `launch` configuration from the `tslint` extension folder to start the extension running in the VS Code Extension Host and also an `attach` configuration from the `tslint-server` folder to attach the debugger to a running TSLint server. + +You can also see the three **Add Config** commands for the folders, `tslint`, `tslint-server`, and `tslint-tests`, in the vscode-tslint [Workspace](https://github.com/Microsoft/vscode-tslint/blob/master/vscode-tslint.code-workspace). The **Add Config** command will either open an existing `launch.json` file in the folder's `.vscode` subfolder or create a new one and display the debugging configuration template drop-down. + +![debugging template drop-down](images/multi-root-workspaces/add-launch-config.png) + +[Variables](/docs/editor/variables-reference.md) used in a configuration (for example `${workspaceFolder}` or the now deprecated `${workspaceRoot}`) are resolved relative to the folder they belong to. It is possible to scope a variable per workspace folder by appending the root folder's name to a variable (separated by a colon). + +### Workspace launch configurations + +Workspace scoped launch configurations live in the `"launch"` section of the workspace configuration file (**Workspaces: Open Workspace Configuration File** in the command palette): + +![Workspace Settings](images/multi-root-workspaces/workspace-settings.png) + + +Alternatively, new launch configurations can be added via the "Add Config (workspace)" entry of the Launch Configuration drop-down menu: + +![Add Config](images/multi-root-workspaces/add-config.png) + +A compound launch configuration can reference the individual launch configurations by name as long as the names are unique within the workspace, for example: + +```json + "compounds": [{ + "name": "Launch Server & Client", + "configurations": [ + "Launch Server", + "Launch Client" + ] + }] +``` + +If the individual launch configuration names are not unique, the qualifying folder can be specified with a more verbose "folder" syntax: + +```json + "compounds": [{ + "name": "Launch Server & Client", + "configurations": [ + "Launch Server", + { + "folder": "Web Client", + "name": "Launch Client" + }, + { + "folder": "Desktop Client", + "name": "Launch Client" + } + ] + }] +``` + +In addition to `compounds` the `launch` section of the workspace configuration file can contain regular launch configurations too. Make sure that all used variables are explicitly scoped to a specific folder because otherwise they are not valid for the workspace. You can find more details about explicitly scoped variables in the [Variables Reference](/docs/editor/variables-reference.md#variables-scoped-per-workspace-folder). + +Here is an example for a launch configuration where the program lives in a folder "Program" and where all files from a folder "Library" should be skipped when stepping: + +```json +"launch": { + "configurations": [{ + "type": "node", + "request": "launch", + "name": "Launch test", + "program": "${workspaceFolder:Program}/test.js", + "skipFiles": [ + "${workspaceFolder:Library}/out/**/*.js" + ] + }] +} +``` + +## Tasks + +Similar to how VS Code searches for debugging configurations, VS Code will also try to autodetect tasks from gulp, grunt, npm, and TypeScript project files across all folders in a workspace as well as search for tasks defined in `tasks.json` files. The location of tasks is indicated by a folder name suffix. Note that tasks defined in `tasks.json` must be version 2.0.0. + +![tasks drop-down](images/multi-root-workspaces/tasks-dropdown.png) + +From the TSLint extension [Workspace](https://github.com/Microsoft/vscode-tslint/blob/master/vscode-tslint.code-workspace) example above, you can see that there are two **configured tasks** from `tasks.json` files in the `tslint` and `tslint-tests` folders and numerous autodetected npm and TypeScript compiler **detected tasks**. + +## Source Control + +With multi-root workspaces there is a **SOURCE CONTROL PROVIDERS** section which gives you an overview when you have multiple active repositories. These can be contributed by several SCM providers; for example, you can have Git repositories side-by-side with TFS workspaces. As you select repositories in this view, you can see the source control details below. + +![multiple scm providers](images/multi-root-workspaces/multiple-scm-providers.png) + +You can use `kbstyle(Ctrl+Click)` or `kbstyle(Shift+Click)` to select multiple repositories. Their details will appear as separate regions underneath. + +## Extensions + +Multi-root workspaces have been available as a preview on Insiders build since the June 2017 [1.14 release](/updates/v1_14.md#preview-multi-root-workspaces) and we've been working with extension authors to help them get ready for the release to Stable. If you are an extension author, you can review our [Adopting Multi Root Workspace APIs](https://github.com/Microsoft/vscode/wiki/Adopting-Multi-Root-Workspace-APIs) guide to learn about VS Code API changes and how to make your extension work well across multiple folders. + +Below are some of the popular extensions which have already adopted the multi-root workspace APIs. + +
+ +**Note**: If an extension doesn't yet support multiple folders, it will still work in the first folder of your multi-root workspace. + +### Extension recommendations + +VS Code supports folder level extension recommendations through the `extensions.json` files under the folder's `.vscode` subfolder. You can also provide global Workspace extension recommendations by adding them to your `.code-workspace` file. You can use the **Extensions: Configure Recommended Extensions (Workspace)** command to open your Workspace file and add extension identifiers ({publisherName}.{extensionName}) to the `extensions.recommendations` array. + +```json +{ + "folders": [ + { + "path": "vscode" + }, + { + "path": "vscode-docs" + } + ], + "extensions": { + "recommendations": [ + "eg2.tslint", + "dbaeumer.vscode-eslint", + "msjsdiag.debugger-for-chrome" + ] + } +} +``` + +## Next steps + +* [Debugging](/docs/editor/debugging.md) - Learn how to set up debugging for your application. +* [Tasks](/docs/editor/tasks.md) - Tasks let you run external tools like compilers within VS Code. + +## Common questions + +### How can I go back to working with a single project folder? + +You can either close the Workspace and open the folder directly or remove the folder from Workspace. + +### As an extension author what do I need to do? + +See our [Adopting Multi Root Workspace APIs](https://github.com/Microsoft/vscode/wiki/Adopting-Multi-Root-Workspace-APIs) guide. Most extensions can easily support multi-root workspaces. diff --git a/docs/editor/portable.md b/docs/editor/portable.md new file mode 100644 index 0000000000000000000000000000000000000000..f28d21596dff41e6c6a1717ed852822a1bf7ec74 --- /dev/null +++ b/docs/editor/portable.md @@ -0,0 +1,91 @@ +--- +Order: +Area: editor +TOCTitle: Portable Mode +ContentId: A5C839C4-67E9-449C-94B8-4B310FCAAB1B +PageTitle: Portable Mode in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code supports a Portable Mode. +--- +# Portable Mode + +Visual Studio Code supports [Portable mode](https://en.wikipedia.org/wiki/Portable_application). This mode enables all data created and maintained by VS Code to live near itself, so it can be moved around across environments. + +This mode also provides a way to set the installation folder location for VS Code extensions, useful for corporate environments that prevent extensions from being installed in the Windows AppData folder. + +Portable mode is supported on the ZIP download for Windows and Linux, as well as the regular Application download for macOS. + +> **Note:** Do not attempt to configure portable mode on a **Windows installation**. Portable mode is only supported on the Windows ZIP archive. Note as well that the Windows ZIP archive does not support auto update. + +## Enable Portable mode + +### Windows, Linux + +After unzipping the VS Code download, simply create a `data` folder within Code's folder: + +``` +|- VSCode-win32-x64-1.25.0-insider +| |- Code.exe (or code executable) +| |- data +| |- ... +``` + +From then on, that folder will be used to contain all Code data, including session state, preferences, extensions, etc. + +The `data` folder can be moved to other VS Code installations. This is useful for updating your portable Code version: simply move the `data` folder to a newer extracted version of VS Code. + +### macOS + +On **macOS**, you need to place the data folder as a sibling of the application itself. Since the folder will be alongside the application, you need to name it specifically so that Code can find it. The default folder name is `code-portable-data`: + + +``` +|- Visual Studio Code.app +|- code-portable-data +``` + +Portable Mode won't work if your application is in [quarantine](https://apple.stackexchange.com/a/104875), which happens by default if you just downloaded Code. Make sure you remove the quarantine attribute, if Portable Mode doesn't seem to work: + +```bash +xattr -dr com.apple.quarantine Visual\ Studio\ Code.app +``` + +**Note:** On Insiders, the folder should be named `code-insiders-portable-data`. + +## Update Portable VS Code + +On **Windows** and **Linux**, you can update VS Code by copying the `data` folder over to a more recent version of VS Code. + +On **macOS**, automatic updates should work as always, no extra work needed. + +## Migrate to Portable mode + +You can also migrate an existing installation to Portable mode: + +1. Download the VS Code ZIP distribution for your platform. +2. Create the `data` or `code-portable-data` folder as above. +3. Copy the user data directory to `data` and rename it to `user-data`: + * **Windows** `%APPDATA%\Code` + * **macOS** `$HOME/Library/Application Support/Code` + * **Linux** `$HOME/.config/Code` +4. Copy the extensions directory to `data`: + * **Windows** `%USERPROFILE%\.vscode\extensions` + * **macOS** `~/.vscode/extensions` + * **Linux** `~/.vscode/extensions` + +Here's the desired outcome on **Windows**: + +``` +|- VSCode-win32-x64-1.25.0-insider +| |- Code.exe (or code executable) +| |- data +| | |- user-data +| | | |- ... +| | |- extensions +| | | |- ... +| |- ... +``` + +## TMP directory + +By default, the default `TMP` directory is still the system one even in Portable Mode, since no state is kept there. If you wish to also have your TMP directory within your portable directory, simply create an empty `tmp` directory inside the `data` folder. As long as a `tmp` directory exists, it will be used for TMP data. diff --git a/docs/editor/refactoring.md b/docs/editor/refactoring.md new file mode 100644 index 0000000000000000000000000000000000000000..33f82135b513e2ac43afbf293b7737ab4cc9a4d6 --- /dev/null +++ b/docs/editor/refactoring.md @@ -0,0 +1,121 @@ +--- +Order: 6 +Area: editor +TOCTitle: Refactoring +ContentId: 481dfd3a-d847-4ed3-b37b-7fc8d234a4c2 +PageTitle: Refactoring source code in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Refactoring source code in Visual Studio Code. +--- +# Refactoring + +[Source code refactoring](https://en.wikipedia.org/wiki/Code_refactoring) can improve the quality and maintainability of your project by restructuring your code while not modifying the runtime behavior. Visual Studio Code supports refactoring operations (refactorings) such as [Extract Method](https://refactoring.com/catalog/extractMethod.html) and [Extract Variable](https://refactoring.com/catalog/extractVariable.html) to improve your code base from within your editor. + +![refactoring hero image](images/refactoring/refactoring-hero.png) + +For example, a common refactoring used to avoid duplicating code (a maintenance headache) is the [Extract Method](https://refactoring.com/catalog/extractMethod.html) refactoring, where you select source code that you'd like to reuse elsewhere and pull it out into its own shared method. + +Refactorings are provided by a language service and VS Code has built-in support for TypeScript and JavaScript refactoring through the [TypeScript](https://www.typescriptlang.org/) language service. Refactoring support for other programming languages is provided through VS Code [extensions](/docs/editor/extension-gallery.md) which contribute language services. The UI and commands for refactoring are the same across languages, and in this topic we'll demonstrate refactoring support with the TypeScript language service. + +## Code Actions = Quick Fixes and refactorings + +In VS Code, Code Actions can provide both refactorings and Quick Fixes for detected issues (highlighted with green squiggles). An available Code Action is announced by a lightbulb near the source code when the cursor is on a squiggle or selected text region. Clicking on the Code Action lightbulb or using the **Quick Fix** command `kb(editor.action.quickFix)` will display Quick Fixes and refactorings. + +If you'd just like to see refactorings without Quick Fixes, you can use the **Refactor** command (`kb(editor.action.refactor)`). + +>**Note:** If you prefer to not see the Code Action lightbulb in your editor, you can disable lightbulbs with the `editor.lightbulb.enable` [setting](/docs/getstarted/settings.md). You can still open Quick Fixes through **Quick Fix** command and `kb(editor.action.quickFix)` keyboard shortcut. + +## Refactoring actions + +### Extract Method + +Select the source code you'd like to extract and then click on the lightbulb in the gutter or press (`kb(editor.action.quickFix)`) to see available refactorings. Source code fragments can be extracted into a new method, or into a new function at various different scopes. During the extract refactoring, you will be prompted to provide a meaningful name. + +### Extract Variable + +TypeScript language service provides **Extract to const** refactoring to create a new local variable for the currently selected expression: + +![Extract local](images/refactoring/ts-extract-local.gif) + +When working with classes, you can also extract a value to a new property. + +## Rename symbol + +Renaming is a common operation related to refactoring source code and VS Code has a separate **Rename Symbol** command (`kb(editor.action.rename)`). Some languages support rename symbol across files. Press `kb(editor.action.rename)` and then type the new desired name and press `kbstyle(Enter)`. All usages of the symbol will be renamed, across files. + +![Rename](images/refactoring/rename.png) + +## Keybindings for Code Actions + +The `editor.action.codeAction` command lets you configure keybindings for specific Code Actions. This keybinding, for example, triggers the **Extract function** refactoring Code Actions: + +```json +{ + "key": "ctrl+shift+r ctrl+e", + "command": "editor.action.codeAction", + "args": { + "kind": "refactor.extract.function" + } +} +``` + +Code Action kinds are specified by extensions using the enhanced `CodeActionProvided` API. Kinds are hierarchical, so `"kind": "refactor"` will show all refactoring Code Actions, whereas `"kind": "refactor.extract.function"` will only show **Extract function** refactorings. + +Using the above keybinding, if only a single `"refactor.extract.function"` Code Action is available, it will be automatically applied. If multiple **Extract function** Code Actions are available, we bring up a context menu to select them: + +![Select Code Action context menu](images/refactoring/code-action-context-menu.png) + +You can also control how/when Code Actions are automatically applied using the `apply` argument: + +```json +{ + "key": "ctrl+shift+r ctrl+e", + "command": "editor.action.codeAction", + "args": { + "kind": "refactor.extract.function", + "apply": "first" + } +} +``` + +Valid values for `"apply"`: + +* `"first"` - Always automatically apply the first available Code Action. +* `"ifSingle"` - Default. Automatically apply the Code Action if only one is available. Otherwise, show the context menu. +* `"never"` - Always show the Code Action context menu, even if only a single Code Action is available. + +When a Code Action keybinding is configured with `"preferred": true`, only preferred Quick Fixes and refactorings are shown. A preferred Quick Fix addresses the underlying error, while a preferred refactoring is the most common refactoring choice. For example, while multiple `refactor.extract.constant` refactorings may exist, each extracting to a different scope in the file, the preferred `refactor.extract.constant` refactoring is the one that extracts to a local variable. + +This keybinding uses `"preferred": true` to create a refactoring that always tries to extract the selected source code to a constant in the local scope: + +```json +{ + "key": "shift+ctrl+e", + "command": "editor.action.codeAction", + "args": { + "kind": "refactor.extract.constant", + "preferred": true, + "apply": "ifsingle" + } +} +``` + +## Extensions with refactorings + +You can find extensions that support refactoring by looking in the VS Code [Marketplace](https://marketplace.visualstudio.com/vscode). You can go to the Extensions view (`kb(workbench.view.extensions)`) and type 'refactor' in the search box. You can then sort by install count or ratings to see which extensions are popular. + +
+ +> Tip: The extensions shown above are dynamically queried. Click on an extension tile above to read the description and reviews to decide which extension is best for you. + +## Next steps + +* [Intro Video - Code Editing](/docs/introvideos/codeediting.md) - Watch an introductory video on code editing features. +* [Code Navigation](/docs/editor/editingevolved) - VS Code lets you move quickly through your source code. +* [Debugging](/docs/editor/debugging.md) - Learn about debugging with VS Code. + +## Common questions + +### Why don't I see any lightbulbs when there are errors in my code? + +Lightbulbs (Code Actions) are only shown when your cursor hovers over the text showing the error. Hovering over the text will show the error description, but you need to move the cursor or select text to see lightbulbs for Quick Fixes and refactorings. diff --git a/docs/editor/tasks-appendix.md b/docs/editor/tasks-appendix.md new file mode 100644 index 0000000000000000000000000000000000000000..12151ef0f6420344934bc93a181a8256d72a45cc --- /dev/null +++ b/docs/editor/tasks-appendix.md @@ -0,0 +1,395 @@ +--- +TOCTitle: Tasks Appendix +ContentId: 6DCA48F5-0566-4AEB-9C4C-CCBBA2945347 +PageTitle: Visual Studio Code Tasks Appendix +DateApproved: 3/7/2019 +MetaDescription: Additional info for using task runners in Visual Studio Code. +--- +# Appendix + +This is additional information for Visual Studio Code [tasks](/docs/editor/tasks.md). + +## Schema for tasks.json + +The following interfaces define the schema of the tasks.json file. + +```typescript + +interface TaskConfiguration extends BaseTaskConfiguration { + + /** + * The configuration's version number + */ + version: "2.0.0"; + + /** + * Windows specific task configuration + */ + windows?: BaseTaskConfiguration; + + /** + * macOS specific task configuration + */ + osx?: BaseTaskConfiguration; + + /** + * Linux specific task configuration + */ + linux?: BaseTaskConfiguration; +} + +interface BaseTaskConfiguration { + + /** + * The type of a custom task. Tasks of type "shell" are executed + * inside a shell (e.g. bash, cmd, powershell, ...) + */ + type: "shell" | "process"; + + /** + * The command to be executed. Can be an external program or a shell + * command. + */ + command: string; + + /** + * Specifies whether a global command is a background task. + */ + isBackground?: boolean; + + /** + * The command options used when the command is executed. Can be omitted. + */ + options?: CommandOptions; + + /** + * The arguments passed to the command. Can be omitted. + */ + args?: string[]; + + /** + * The presentation options. + */ + presentation?: PresentationOptions; + + /** + * The problem matcher to be used if a global command is executed (e.g. no tasks + * are defined). A tasks.json file can either contain a global problemMatcher + * property or a tasks property but not both. + */ + problemMatcher?: string | ProblemMatcher | (string | ProblemMatcher)[]; + + /** + * The configuration of the available tasks. A tasks.json file can either + * contain a global problemMatcher property or a tasks property but not both. + */ + tasks?: TaskDescription[]; +} + + +/** + * Options to be passed to the external program or shell + */ +export interface CommandOptions { + + /** + * The current working directory of the executed program or shell. + * If omitted the current workspace's root is used. + */ + cwd?: string; + + /** + * The environment of the executed program or shell. If omitted + * the parent process' environment is used. + */ + env?: { [key:string]:string; }; + + /** + * Configuration of the shell when task type is `shell` + */ + shell: { + + /** + * The shell to use. + */ + executable: string; + + /** + * The arguments to be passed to the shell executable to run in command mode + * (e.g ['-c'] for bash or ['/S', '/C'] for cmd.exe). + */ + args?: string[]; + } +} + +/** + * The description of a task. + */ +interface TaskDescription { + + /** + * The task's name + */ + label: string; + + /** + * The type of a custom task. Tasks of type "shell" are executed + * inside a shell (e.g. bash, cmd, powershell, ...) + */ + type: "shell" | "process"; + + /** + * The command to execute. If the type is "shell" it should be the full + * command line including any additional arguments passed to the command. + */ + command: string; + + /** + * Whether the executed command is kept alive and runs in the background. + */ + isBackground?: boolean; + + /** + * Additional arguments passed to the command. Should be used if type + * is "process". + */ + args?: string[]; + + /** + * Defines the group to which this task belongs. Also supports to mark + * a task as the default task in a group. + */ + group?: "build" | "test" | { kind: "build" | "test"; isDefault: boolean }; + + /** + * The presentation options. + */ + presentation?: PresentationOptions; + + /** + * The problem matcher(s) to use to capture problems in the tasks + * output. + */ + problemMatcher?: string | ProblemMatcher | (string | ProblemMatcher)[]; + + /** + * Defines when and how a task is run. + */ + runOptions?: RunOptions; +} + +interface PresentationOptions { + + /** + * Controls whether the task output is reveal in the user interface. + * Defaults to `always`. + */ + reveal?: "never" | "silent" | "always"; + + /** + * Controls whether the command associated with the task is echoed + * in the user interface. + */ + echo?: boolean; + + /** + * Controls whether the panel showing the task output is taking focus. + */ + focus?: boolean; + + /** + * Controls if the task panel is used for this task only (dedicated), + * shared between tasks (shared) or if a new panel is created on + * every task execution (new). Defaults to `shared` + */ + panel?: "shared" | "dedicated" | "new"; +} + +/** + * A description of a problem matcher that detects problems + * in build output. + */ +interface ProblemMatcher { + + /** + * The name of a base problem matcher to use. If specified the + * base problem matcher will be used as a template and properties + * specified here will replace properties of the base problem + * matcher + */ + base?: string; + + /** + * The owner of the produced VS Code problem. This is typically + * the identifier of a VS Code language service if the problems are + * to be merged with the one produced by the language service + * or 'external'. Defaults to 'external' if omitted. + */ + owner?: string; + + /** + * The severity of the VS Code problem produced by this problem matcher. + * + * Valid values are: + * "error": to produce errors. + * "warning": to produce warnings. + * "info": to produce infos. + * + * The value is used if a pattern doesn't specify a severity match group. + * Defaults to "error" if omitted. + */ + severity?: string; + + /** + * Defines how filename reported in a problem pattern + * should be read. Valid values are: + * - "absolute": the filename is always treated absolute. + * - "relative": the filename is always treated relative to + * the current working directory. This is the default. + * - ["relative", "path value"]: the filename is always + * treated relative to the given path value. + */ + fileLocation?: string | string[]; + + /** + * The name of a predefined problem pattern, the inline definition + * of a problem pattern or an array of problem patterns to match + * problems spread over multiple lines. + */ + pattern?: string | ProblemPattern | ProblemPattern[]; + + /** + * Additional information used to detect when a background task (like a watching task in Gulp) + * is active. + */ + background?: BackgroundMatcher; +} + +/** + * A description to track the start and end of a background task. + */ +interface BackgroundMatcher { + + /** + * If set to true the watcher is in active mode when the task + * starts. This is equals of issuing a line that matches the + * beginPattern. + */ + activeOnStart?: boolean; + + /** + * If matched in the output the start of a background task is signaled. + */ + beginsPattern?: string; + + /** + * If matched in the output the end of a background task is signaled. + */ + endsPattern?: string; +} + +interface ProblemPattern { + + /** + * The regular expression to find a problem in the console output of an + * executed task. + */ + regexp: string; + + /** + * Whether the pattern matches a problem for the whole file or for a location + * inside a file. + * + * Defaults to "location". + */ + kind?: "file" | "location"; + + /** + * The match group index of the filename. + */ + file: number; + + /** + * The match group index of the problem's location. Valid location + * patterns are: (line), (line,column) and (startLine,startColumn,endLine,endColumn). + * If omitted the line and column properties are used. + */ + location?: number; + + /** + * The match group index of the problem's line in the source file. + * Can only be omitted if location is specified. + */ + line?: number; + + /** + * The match group index of the problem's column in the source file. + */ + column?: number; + + /** + * The match group index of the problem's end line in the source file. + * + * Defaults to undefined. No end line is captured. + */ + endLine?: number; + + /** + * The match group index of the problem's end column in the source file. + * + * Defaults to undefined. No end column is captured. + */ + endColumn?: number; + + /** + * The match group index of the problem's severity. + * + * Defaults to undefined. In this case the problem matcher's severity + * is used. + */ + severity?: number; + + /** + * The match group index of the problem's code. + * + * Defaults to undefined. No code is captured. + */ + code?: number; + + /** + * The match group index of the message. Defaults to 0. + */ + message: number; + + /** + * Specifies if the last pattern in a multi line problem matcher should + * loop as long as it does match a line consequently. Only valid on the + * last problem pattern in a multi line problem matcher. + */ + loop?: boolean; +} + +/** + * A description to when and how run a task. + */ +interface RunOptions { + + /** + * Controls how variables are evaluated when a task is executed through + * the Rerun Last Task command. + * The default is `true`, meaning that variables will be re-evaluated when + * a task is rerun. When set to `false`, the resolved variable values from + * the previous run of the task will be used. + */ + reevaluateOnRerun?: boolean; + + /** + * Specifies when a task is run. + * + * Valid values are: + * "default": The task will only be run when executed through the Run Task command. + * "folderOpen": The task will be run when the containing folder is opened. + */ + runOn?: string; +} +``` diff --git a/docs/editor/tasks-v1-appendix.md b/docs/editor/tasks-v1-appendix.md new file mode 100644 index 0000000000000000000000000000000000000000..9cc2705a78b508606ad0d2baf998ea000cc65853 --- /dev/null +++ b/docs/editor/tasks-v1-appendix.md @@ -0,0 +1,350 @@ +--- +TOCTitle: Tasks Appendix +ContentId: 91d666bc-6f1a-4b9e-8476-4f1bcd24e75b +PageTitle: Visual Studio Code Tasks Appendix (legacy version) +DateApproved: 3/7/2019 +MetaDescription: Additional info for using task runners in Visual Studio Code. +--- +# Appendix (legacy version) + +This is additional information for Visual Studio Code [tasks](/docs/editor/tasks-v1.md). + +## Schema for tasks.json + +The following interfaces define the schema of the tasks.json file. + +```typescript + +interface TaskConfiguration extends BaseTaskConfiguration { + + /** + * The configuration's version number + */ + version: string; + + /** + * Windows specific task configuration + */ + windows?: BaseTaskConfiguration; + + /** + * macOS specific task configuration + */ + osx?: BaseTaskConfiguration; + + /** + * Linux specific task configuration + */ + linux?: BaseTaskConfiguration; +} + +interface BaseTaskConfiguration { + + /** + * The command to be executed. Can be an external program or a shell + * command. + */ + command: string; + + /** + * Specifies whether the command is a shell command and therefore must + * be executed in a shell interpreter (e.g. cmd.exe, bash, ...). + * + * Defaults to false if omitted. + */ + isShellCommand?: boolean | ShellConfiguration; + + /** + * Specifies whether a global command is a background task. + */ + isBackground?: boolean; + + /** + * The command options used when the command is executed. Can be omitted. + */ + options?: CommandOptions; + + /** + * The arguments passed to the command. Can be omitted. + */ + args?: string[]; + + /** + * Controls whether the output view of the running tasks is brought to front or not. + * + * Valid values are: + * "always": bring the output window always to front when a task is executed. + * "silent": only bring it to front if no problem matcher is defined for the task executed. + * "never": never bring the output window to front. + * + * If omitted "always" is used. + */ + showOutput?: string; + + /** + * If set to false the task name is added as an additional argument to the + * command when executed. If set to true the task name is suppressed. If + * omitted false is used. + */ + suppressTaskName?: boolean; + + /** + * Some commands require that the task argument is highlighted with a special + * prefix (e.g. /t: for MSBuild). This property can be used to control such + * a prefix. + */ + taskSelector?:string; + + /** + * The problem matcher to be used if a global command is executed (e.g. no tasks + * are defined). A tasks.json file can either contain a global problemMatcher + * property or a tasks property but not both. + */ + problemMatcher?: string | ProblemMatcher | (string | ProblemMatcher)[]; + + /** + * The configuration of the available tasks. A tasks.json file can either + * contain a global problemMatcher property or a tasks property but not both. + */ + tasks?: TaskDescription[]; +} + +/** + * Configuration of the shell when run in terminal + */ +export interface ShellConfiguration { + + /** + * The shell executable. + */ + executable: string; + + /** + * The arguments to be passed to the shell executable. + */ + args?: string[]; +} + +/** + * Options to be passed to the external program or shell + */ +export interface CommandOptions { + + /** + * The current working directory of the executed program or shell. + * If omitted the current workspace's root is used. + */ + cwd?: string; + + /** + * The environment of the executed program or shell. If omitted + * the parent process' environment is used. + */ + env?: { [key:string]:string; }; +} + +/** + * The description of a task. + */ +export interface TaskDescription { + + /** + * The task's name + */ + taskName: string; + + /** + * Additional arguments passed to the command when this task is + * executed. + */ + args?: string[]; + + /** + * Whether this task maps to the default build command. + */ + isBuildCommand?:boolean; + + /** + * Whether this task maps to the default test command. + */ + isTestCommand?: boolean; + + /** + * Whether the executed command is kept alive and runs in the background. + */ + isBackground?: boolean; + + /** + * Controls whether the output view of the running tasks is brought to front or not. + * See BaseTaskConfiguration#showOutput for details. + */ + showOutput?: string; + + /** + * See BaseTaskConfiguration#suppressTaskName for details. + */ + suppressTaskName?: boolean; + + /** + * The problem matcher(s) to use to capture problems in the tasks + * output. + */ + problemMatcher?: string | ProblemMatcher | (string | ProblemMatcher)[]; +} + +/** + * A description of a problem matcher that detects problems + * in build output. + */ +export interface ProblemMatcher { + + /** + * The name of a base problem matcher to use. If specified the + * base problem matcher will be used as a template and properties + * specified here will replace properties of the base problem + * matcher + */ + base?: string; + + /** + * The owner of the produced VS Code problem. This is typically + * the identifier of a VS Code language service if the problems are + * to be merged with the one produced by the language service + * or 'external'. Defaults to 'external' if omitted. + */ + owner?: string; + + /** + * The severity of the VS Code problem produced by this problem matcher. + * + * Valid values are: + * "error": to produce errors. + * "warning": to produce warnings. + * "info": to produce infos. + * + * The value is used if a pattern doesn't specify a severity match group. + * Defaults to "error" if omitted. + */ + severity?: string; + + /** + * Defines how filename reported in a problem pattern + * should be read. Valid values are: + * - "absolute": the filename is always treated absolute. + * - "relative": the filename is always treated relative to + * the current working directory. This is the default. + * - ["relative", "path value"]: the filename is always + * treated relative to the given path value. + */ + fileLocation?: string | string[]; + + /** + * The name of a predefined problem pattern, the inline definition + * of a problem pattern or an array of problem patterns to match + * problems spread over multiple lines. + */ + pattern?: string | ProblemPattern | ProblemPattern[]; + + /** + * Additional information used to detect when a background task (like a watching task in Gulp) + * is active. + */ + watching?: WatchingMatcher; +} + +/** + * A description to track the start and end of a watching task. + */ +export interface WatchingMatcher { + + /** + * If set to true the watcher is in active mode when the task + * starts. This is equals of issuing a line that matches the + * beginPattern. + */ + activeOnStart?: boolean; + + /** + * If matched in the output the start of a watching task is signaled. + */ + beginsPattern?: string; + + /** + * If matched in the output the end of a watching task is signaled. + */ + endsPattern?: string; +} + +export interface ProblemPattern { + + /** + * The regular expression to find a problem in the console output of an + * executed task. + */ + regexp: string; + + /** + * The match group index of the filename. + */ + file: number; + + /** + * The match group index of the problem's location. Valid location + * patterns are: (line), (line,column) and (startLine,startColumn,endLine,endColumn). + * If omitted the line and column properties are used. + */ + location?: number; + + /** + * The match group index of the problem's line in the source file. + * Can only be omitted if location is specified. + */ + line?: number; + + /** + * The match group index of the problem's column in the source file. + */ + column?: number; + + /** + * The match group index of the problem's end line in the source file. + * + * Defaults to undefined. No end line is captured. + */ + endLine?: number; + + /** + * The match group index of the problem's end column in the source file. + * + * Defaults to undefined. No end column is captured. + */ + endColumn?: number; + + /** + * The match group index of the problem's severity. + * + * Defaults to undefined. In this case the problem matcher's severity + * is used. + */ + severity?: number; + + /** + * The match group index of the problem's code. + * + * Defaults to undefined. No code is captured. + */ + code?: number; + + /** + * The match group index of the message. Defaults to 0. + */ + message: number; + + /** + * Specifies if the last pattern in a multi line problem matcher should + * loop as long as it does match a line consequently. Only valid on the + * last problem pattern in a multi line problem matcher. + */ + loop?: boolean; +} +``` diff --git a/docs/editor/tasks-v1.md b/docs/editor/tasks-v1.md new file mode 100644 index 0000000000000000000000000000000000000000..d90f67339fae6488a91b2bf7810a42529c9b018a --- /dev/null +++ b/docs/editor/tasks-v1.md @@ -0,0 +1,592 @@ +--- +Order: +Area: editor +TOCTitle: Tasks +ContentId: 8cdc7d99-6339-49ac-9a31-55f6563fab5c +PageTitle: Visual Studio Code Tasks (legacy version) +DateApproved: 3/7/2019 +MetaDescription: Expand your development workflow with task integration in Visual Studio Code (Gulp, Grunt, Jake and more). +--- +# Tasks (legacy version) + +--- + +This documentation describes the legacy Tasks system in Visual Studio Code version 1.13 and earlier. If you want to learn about the latest Tasks 2.0, please refer to the [Tasks](/docs/editor/tasks.md) topic. + +--- + +Developers use lots of tools, mostly run from the command line, to automate jobs outside the inner software development loop (edit, compile, test and debug). Given their importance in the development life-cycle, it is very helpful to be able to run them and analyze their results from within Visual Studio Code. + +>**Note:** Task support is only available when working on a workspace folder. It is not available when editing single files. + +## Hello World + +Let's start with a simple "Hello World" task which will display text to the **OUTPUT** panel when run. + +Create an empty folder "mytask" and start VS Code from that folder. + +```bash +mkdir mytask +cd mytask +code . +``` + +Tasks are defined in a workspace `tasks.json` file and VS Code has templates for common task runners. In the **Command Palette** (`kb(workbench.action.showCommands)`), you can filter on 'task' and can see the various Task related commands. + +![tasks in command palette](images/tasks/tasks-command-palette.png) + +Select the **Tasks: Configure Task Runner** command and you will see a list of task runner templates. Select **Others** to create a task which runs an external command. + +>**Note:** If you don't see the list of task runner templates, you may already have a `tasks.json` file in your folder and its contents will be open in the editor. Close the file and either delete or rename it for this example. + +You should now see a `tasks.json` file in your workspace `.vscode` folder with the following content: + +```json +{ + "version": "0.1.0", + "command": "echo", + "isShellCommand": true, + "args": ["Hello World"], + "showOutput": "always" +} +``` + +In this example, we are just running the `echo` shell command with "Hello World" as an argument. + +Test the `echo` task by running **Tasks: Run Task** and selecting `echo` from the drop-down list. The **OUTPUT** panel will open and you'll see the text "Hello World". + +You can get IntelliSense on `tasks.json` variables and their values with hover and trigger smart completions with `kb(editor.action.triggerSuggest)`. + +![tasks IntelliSense](images/tasks/tasks-intellisense.png) + +>**Tip:** You can run your task through **Quick Open** (`kb(workbench.action.quickOpen)`) by typing 'task', `kbstyle(Space)` and the command name. In this case, 'task echo'. + +## Output Window Behavior + +Sometimes you will want to control how the output window behaves when running tasks. For instance, you may want to maximize editor space and only look at task output if you think there is a problem. The property `showOutput` controls this and the valid values are: + +- **always** - The output window is always brought to front. This is the default. +- **never** - The user must explicitly bring the output window to the front using the **View** > **Output** command (`kb(workbench.action.output.toggleOutput)`). +- **silent** - The output window is brought to front only if no [problem matchers](/docs/editor/tasks.md#processing-task-output-with-problem-matchers) are set for the task. + +### echoCommand + +To see the exact command VS Code is running, you can enable the `echoCommand` setting in `tasks.json`: + +![tasks echoCommand](images/tasks/tasks-echoCommand.png) + +>**Note:** VS Code ships with predefined `tasks.json` templates to run npm, MSBuild, Maven and other command line tools. A great way to learn about tasks is to review these templates and see which tools or task runners are similar to other tools you may be using. + +## command and tasks[] + +`tasks.json` takes a single `command` value which can be a task runner like gulp or grunt or any command line tool like a compiler or linter. By default, the `command` will show up in the **Tasks: Run Task** drop-down list. + +You can also define multiple tasks in a `tasks` array in order to pass different arguments or use different settings when the `command` is run. + +Here's a simple example passing different arguments to the `echo` command: + +```json +{ + "version": "0.1.0", + "command": "echo", + "isShellCommand": true, + "args": [], + "showOutput": "always", + "echoCommand": true, + "suppressTaskName": true, + "tasks": [ + { + "taskName": "hello", + "args": ["Hello World"] + }, + { + "taskName": "bye", + "args": ["Good Bye"] + } + ] +} +``` + +Now when you run **Tasks: Run Task**, you will now see two tasks in the drop-down list, `hello` and `bye`. We set `suppressTaskName` to true as by default the task name is also passed to the command which would result in "echo hello Hello World". + +![tasks array](images/tasks/tasks-array.png) + +Some `tasks.json` properties such as `showOutput` and `suppressTaskName` can be set both globally and then overridden in specific tasks. The `tasks` `args` property values are appended to the global arguments. The final command line is constructed as follows: + +* If `suppressTaskName` is `true`, the command line is `command 'global args' 'task args'`. +* If `suppressTaskName` is `false`, it is `command 'global args' taskName 'task args'`. + +There are also `tasks` specific properties. One useful property is `isBuildCommand`, which if set to true, will run the task with the **Tasks: Run Build Task** (`kb(workbench.action.tasks.build)`) command. + +## Running multiple commands + +If you want to run multiple different commands you can specify different commands per task. A `tasks.json` file using commands per task looks like this: + +```json +{ + "version": "0.1.0", + "tasks": [ + { + "taskName": "tsc", + "command": "tsc", + "args": ["-w"], + "isShellCommand": true, + "isBackground": true, + "problemMatcher": "$tsc-watch" + }, + { + "taskName": "build", + "command": "gulp", + "args": ["build"], + "isShellCommand": true + } + ] +} +``` + +The first task starts the TypeScript compiler in watch mode, the second one starts the gulp build. If a task specifies a local command to run, the task name is not included into the command line (`suppressTaskName` is `true` by default for these tasks). Since a local command can specify local arguments, there is no need for adding it by default. If a `tasks.json` file specifies both global and task local commands, the task local commands win over the global command. There is no merging between a global and a task local command. + +## Binding keyboard shortcuts to tasks + +If you need to run a task frequently, you can also define a keyboard shortcut for the task. + +For example, to bind `kbstyle(Ctrl+H)` to the `build` task from above, add the following to your `keybindings.json` file: + +```json +{ + "key": "ctrl+h", + "command": "workbench.action.tasks.runTask", + "args": "build" +} +``` + +## Variable substitution + +When authoring tasks configurations, it is useful to have a set of predefined common variables such as the active file (`${file}`) or workspace root folder (`${workspaceFolder}`). VS Code supports variable substitution inside strings in the `tasks.json` file and you can see a full list of predefined variables in the [Variables Reference](/docs/editor/variables-reference.md). + +Below is an example of a configuration that passes the current opened file to the TypeScript compiler. + +```json +{ + "command": "tsc", + "args": ["${file}"] +} +``` + +## Operating System Specific Properties + +The task system supports defining values (for example, the command to be executed) specific to an operating system. To do so, put an operating system specific literal into the `tasks.json` file and specify the corresponding properties inside that literal. + +Below is an example that uses the Node.js executable as a command and is treated differently on Windows and Linux: + +```json +{ + "version": "0.1.0", + "windows": { + "command": "C:\\Program Files\\nodejs\\node.exe" + }, + "linux": { + "command": "/usr/bin/node" + } +} +``` + +Valid operating properties are `windows` for Windows, `linux` for Linux and `osx` for macOS. Properties defined in an operating system specific scope override properties defined in the global scope. + +In the example below: + +```json +{ + "version": "0.1.0", + "showOutput": "never", + "windows": { + "showOutput": "always" + } +} +``` + +Output from the executed task is never brought to front except for Windows where it is always shown. + +Tasks local commands can be made operating specific as well. The syntax is the same as for global commands. Here an example that adds an OS specific argument to a command: + +```json +{ + "version": "0.1.0", + "tasks": [ + { + "taskName": "build", + "command": "gulp", + "isShellCommand": true, + "windows": { + "args": ["build", "win32"] + }, + "linux": { + "args": ["build", "linux"] + }, + "osx": { + "args": ["build", "osx"] + } + } + ] +} +``` + +## Examples of Tasks in Action + +To highlight the power of Tasks, here are a few examples of how VS Code can use Tasks to integrate external tools like linters and compilers. + +### Transpiling TypeScript to JavaScript + +The [TypeScript topic](/docs/languages/typescript.md#transpiling-typescript-into-javascript) includes an example that creates a task to transpile TypeScript to JavaScript and observe any related errors from within VS Code. + +### Compiling Markdown to HTML + +The Markdown topic provides two examples for compiling Markdown to HTML: + +1. [Manually compiling with a Build task](/docs/languages/markdown.md#compiling-markdown-into-html) +2. [Automation of the compile step with a file watcher](/docs/languages/markdown.md#automating-markdown-compilation) + +### Transpiling Less and SCSS into CSS + +The CSS topic provides examples of how to use Tasks to generate CSS files. + +1. [Manually transpiling with a Build task](/docs/languages/css.md#transpiling-sass-and-less-into-css) +2. [Automation of the compile step with a file watcher](/docs/languages/css.md#automating-sassless-compilation) + +## Autodetecting Gulp, Grunt and Jake Tasks + +VS Code can autodetect tasks from within Gulp, Grunt and Jake files. This adds their tasks to the task list without requiring additional configuration (unless you need to use a problem matcher, more on that in a moment). + +To help make this example more concrete, let's use this simple Gulp file. This defines two tasks: build and debug. The first compiles C# code using [Mono](https://www.mono-project.com/)'s compiler. The second starts the MyApp under the Mono debugger. + +```javascript +var gulp = require("gulp"); + +var program = "MyApp"; +var port = 55555; + +gulp.task('default', ['debug']); + +gulp.task('build', function() { + return gulp + .src('./**/*.cs') + .pipe(msc(['-fullpaths', '-debug', '-target:exe', '-out:' + program])); +}); + +gulp.task('debug', ['build'], function(done) { + return mono.debug({ port: port, program: program}, done); +}); +``` + +Pressing `kb(workbench.action.showCommands)` and then typing `Run Task` followed by `kbstyle(Enter)` will list all available tasks. Selecting one and pressing `kbstyle(Enter)` will execute the task. + +![Task list](images/tasks/gulpautodetect.png) + +>**Note:** Gulp, Grunt and Jake are autodetected only if the corresponding files (for example `gulpfile.js`) are present in the root of the opened folder. + +## Processing Task Output with Problem Matchers + +VS Code can process the output from a task with a problem matcher and we ship with a number of them 'in the box': + +- **TypeScript**: `$tsc` assumes that file names in the output are relative to the opened folder. +- **TypeScript Watch**: `$tsc-watch` matches problems reported from the `tsc` compiler when executed in watch mode. +- **JSHint**: `$jshint` assumes that file names are reported as an absolute path. +- **JSHint Stylish**: `$jshint-stylish` assumes that file names are reported as an absolute path. +- **ESLint Compact**: `$eslint-compact` assumes that file names in the output are relative to the opened folder. +- **ESLint Stylish**: `$eslint-stylish` assumes that file names in the output are relative to the opened folder. +- **Go**: `$go` matches problems reported from the `go` compiler. Assumes that file names are relative to the opened folder. +- **CSharp and VB Compiler**: `$mscompile` assumes that file names are reported as an absolute path. +- **Less**: `$lessCompile` assumes that file names are reported as absolute path. + +Problem matchers scan the task output text for known warning or error strings and report these inline in the editor and in the Problems panel. Problem matchers can be set globally or in a specific task entry. + +You can also create your own problem matcher which we'll talk about soon. + +## Mapping Gulp, Grunt and Jake Output to Problem Matchers + +You need to configure the tasks in a `tasks.json` file (located under your workspace `.vscode` folder) if you want to do more than just run the task. For example, you might want to match reported problems and highlight them within VS Code, or to trigger a build task using the **Tasks: Run Build Task** command (`kb(workbench.action.tasks.build)`). + +If you don't already have a `tasks.json` under your workspace `.vscode` folder, running the **Tasks: Configure Task Runner** action from the **Command Palette** (`kb(workbench.action.showCommands)`) will offer you a set of templates to pick from. + +For this example, select `Gulp` from the list. Given a `gulpfile.js` like the example above, this will generate a `tasks.json` file like this: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "0.1.0", + "command": "gulp", + "isShellCommand": true, + "args": [ + "--no-color" + ], + "tasks": [ + { + "taskName": "build", + "args": [], + "isBuildCommand": true, + "problemMatcher": [ + "$lessCompile", + "$tsc", + "$jshint" + ] + } + ] +} +``` + +Since we execute the Mono compiler to compile C# files, we should use the `$msCompile` problem matcher to detect any problems reported by the compiler. + +The `problemMatcher` property will then be: + +```json + "problemMatcher": [ + "$msCompile" + ] +``` + +Several things to note about this `tasks.json`: + +1. We want to run the gulp command in a shell (VS Code directly executing it) so we used **isShellCommand**. +2. We added an explicit **tasks** property which allowed us to *optionally* augment a task that was in the `gulpfile.js`. +3. We defined a problem matcher **$msCompile** to process the output - since we are compiling C# using the Mono compiler, the built-in one works as *msc* adheres to the Microsoft compiler pattern. + +## Defining a Problem Matcher + +VS Code ships some of the most common problem matchers out of the box. However, there are lots of compilers and linting tools out there, all of which produce their own style of errors and warnings. So let's talk about how to make your own problem matcher. + +We have a `helloWorld.c` program in which the developer mistyped **printf** as **prinft**. Compiling it with [gcc](https://gcc.gnu.org/) will produce the following warning: + +```bash +helloWorld.c:5:3: warning: implicit declaration of function ‘prinft’ +``` + +We want to produce a problem matcher that can capture the message in the output and show a corresponding problem in VS Code. Problem matchers heavily rely on [regular expressions](https://en.wikipedia.org/wiki/Regular_expression). The section below assumes you are familiar with regular expressions. + +>**Tip:** We have found the [RegEx101 playground](https://regex101.com/) a really good way to develop and test regular expressions. + +A matcher that captures the above warning (and errors) looks like: + +```json +{ + // The problem is owned by the cpp language service. + "owner": "cpp", + // The file name for reported problems is relative to the opened folder. + "fileLocation": ["relative", "${workspaceFolder}"], + // The actual pattern to match problems in the output. + "pattern": { + // The regular expression. Example to match: helloWorld.c:5:3: warning: implicit declaration of function ‘printf’ [-Wimplicit-function-declaration] + "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$", + // The first match group matches the file name which is relative. + "file": 1, + // The second match group matches the line on which the problem occurred. + "line": 2, + // The third match group matches the column at which the problem occurred. + "column": 3, + // The fourth match group matches the problem's severity. Can be ignored. Then all problems are captured as errors. + "severity": 4, + // The fifth match group matches the message. + "message": 5 + } +} +``` + +Please note that the file, line and message properties are mandatory. + +Here is a finished `tasks.json` file with the code above (comments removed) wrapped with the actual task details: + +```json +{ + "version": "0.1.0", + "command": "gcc", + "args": ["-Wall", "helloWorld.c", "-o", "helloWorld"], + "problemMatcher": { + "owner": "cpp", + "fileLocation": ["relative", "${workspaceFolder}"], + "pattern": { + "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$", + "file": 1, + "line": 2, + "column": 3, + "severity": 4, + "message": 5 + } + } +} +``` + +Running it inside VS Code and pressing `kb(workbench.actions.view.problems)` to get the list of problems gives you the following output: + +![GCC Problem Matcher](images/tasks/problemmatcher.png) + +There are a couple more properties that can be used inside a pattern. These are: + +- **location** if the problem location is line or line,column or startLine,startColumn,endLine,endColumn then our generic location match group can be used. +- **endLine** the match group index for the problem's end line. Can be omitted if no end line value is provided by the compiler. +- **endColumn** the match group index for the problem's end column. Can be omitted if no end column value is provided by the compiler. +- **code** the match group index for the problem's code. Can be omitted if no code value is provided by the compiler. + +>**Note:** A functional pattern must at least provide a match group for file, message and line or location. + +## Defining a Multiline Problem Matcher + +Some tools spread problems found in a source file over several lines, especially if stylish reporters are used. An example is [ESLint](https://eslint.org/); in stylish mode it produces output like this: + +```bash +test.js + 1:0 error Missing "use strict" statement strict +✖ 1 problems (1 errors, 0 warnings) +``` + +Our problem matcher is line-based so we need to capture the file name (test.js) with a different regular expression than the actual problem location and message (1:0 error Missing "use strict" statement). + +To do this we use an array of problem patterns for the `pattern` property. This way you define a pattern per each line you want to match. + +The following problem pattern matches the output from ESLint in stylish mode - but still has one small issue which we will resolve next. The code below has a first regular expression to capture the file name and the second to capture the line, column, severity, message and error code: + +```json +{ + "owner": "javascript", + "fileLocation": ["relative", "${workspaceFolder}"], + "pattern": [ + { + "regexp": "^([^\\s].*)$", + "file": 1 + }, + { + "regexp": "^\\s+(\\d+):(\\d+)\\s+(error|warning|info)\\s+(.*)\\s\\s+(.*)$", + "line": 1, + "column": 2, + "severity": 3, + "message": 4, + "code": 5 + } + ] +} +``` + +Of course it's never quite that simple, and this pattern will not work if there is more than one problem on a resource. For instance, imagine the following output from ESLint: + +```bash +test.js + 1:0 error Missing "use strict" statement strict + 1:9 error foo is defined but never used no-unused-vars + 2:5 error x is defined but never used no-unused-vars + 2:11 error Missing semicolon semi + 3:1 error "bar" is not defined no-undef + 4:1 error Newline required at end of file but not found eol-last +✖ 6 problems (6 errors, 0 warnings) +``` + +The pattern's first regular expression will match "test.js", the second "1:0 error ...". The next line "1:9 error ..." is processed but not matched by the first regular expression and so no problem is captured. + +To make this work, the last regular expression of a multiline pattern can specify the `loop` property. If set to true, it instructs the task system to apply the last pattern of a multiline matcher to the lines in the output as long as the regular expression matches. + +The information captured by all previous patterns is combined with the information captured by the last pattern and turned into a problem inside VS Code. + +Here is a problem matcher to fully capture ESLint stylish problems: + +```json +{ + "owner": "javascript", + "fileLocation": ["relative", "${workspaceFolder}"], + "pattern": [ + { + "regexp": "^([^\\s].*)$", + "file": 1 + }, + { + "regexp": "^\\s+(\\d+):(\\d+)\\s+(error|warning|info)\\s+(.*)\\s\\s+(.*)$", + "line": 1, + "column": 2, + "severity": 3, + "message": 4, + "code": 5, + "loop": true + } + ] +} +``` + +## Background / Watching tasks + +Some tools support running in the background while watching the file system for changes and then triggering an action when a file changes on disk. With `Gulp` such functionality is provided through the npm module [gulp-watch](https://www.npmjs.com/package/gulp-watch). The TypeScript compiler `tsc` has built in support for this via the `--watch command` line option. + +To provide feedback that a background task is active in VS Code and producing problem results, a problem matcher has to use additional information to detect these `state` changes in the output. Let's take the `tsc` compiler as an example. When the compiler is started in watch mode, it prints the following additional information to the console: + +``` +> tsc --watch +12:30:36 PM - Compilation complete. Watching for file changes. +``` + +When a file changes on disk which contains a problem, the following output appears: + +``` +12:32:35 PM - File change detected. Starting incremental compilation... +src/messages.ts(276,9): error TS2304: Cannot find name 'candidate'. +12:32:35 PM - Compilation complete. Watching for file changes. +``` + +Looking at the output shows the following pattern: + +- The compiler runs when `File change detected. Starting incremental compilation...` is printed to the console. +- The compiler stops when `Compilation complete. Watching for file changes.` is printed to the console. +- Between those two strings problems are reported. +- The compiler also runs once the initial start (without printing `File change detected. Starting incremental compilation...` to the console). + +To capture this information, a problem matcher can provide a `watching` property. + +For the tsc compiler, this looks like follows: + +```json +"watching": { + "activeOnStart": true, + "beginsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - File change detected\\. Starting incremental compilation\\.\\.\\.", + "endsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - Compilation complete\\. Watching for file changes\\." +} +``` + +In addition to the `watching` property on the problem matcher, the task itself has to be marked as `isBackground` so that the task keeps running in the background. + +A full handcrafted `tasks.json` for a tsc task running in watch mode looks like this: + +```json +{ + "version": "0.1.0", + "command": "tsc", + "suppressTaskName": true, + "tasks": [ + { + "taskName": "watch", + "args": ["--watch"], + "isBackground": true, + "problemMatcher": { + "owner": "typescript", + "fileLocation": "relative", + "pattern": { + "regexp": "^([^\\s].*)\\((\\d+|\\,\\d+|\\d+,\\d+,\\d+,\\d+)\\):\\s+(error|warning|info)\\s+(TS\\d+)\\s*:\\s*(.*)$", + "file": 1, + "location": 2, + "severity": 3, + "code": 4, + "message": 5 + }, + "watching": { + "activeOnStart": true, + "beginsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - File change detected\\. Starting incremental compilation\\.\\.\\.", + "endsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - Compilation complete\\. Watching for file changes\\." + } + } + } + ] +} +``` + +## Next steps + +That was tasks - let's keep going... + +* [tasks.json Schema](/docs/editor/tasks-v1-appendix.md) - You can review the full `tasks.json` schema and descriptions. +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code.* [Language Support](/docs/languages/overview.md) - Learn about our supported programming languages, both shipped with VS Code and through community extensions. +* [Debugging](/docs/editor/debugging.md) - Debug your source code directly in the VS Code editor. diff --git a/docs/editor/tasks.md b/docs/editor/tasks.md new file mode 100644 index 0000000000000000000000000000000000000000..aa2993dc494086dbc312cc81db2da08f7676c4d7 --- /dev/null +++ b/docs/editor/tasks.md @@ -0,0 +1,932 @@ +--- +Order: 11 +Area: editor +TOCTitle: Tasks +ContentId: F5EA1A52-1EF2-4127-ABA6-6CEF5447C608 +PageTitle: Tasks in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Expand your development workflow with task integration in Visual Studio Code. +--- +# Integrate with External Tools via Tasks + +--- + +If you are using Visual Studio Code version 1.13 or earlier, please refer to the previous version of the Tasks [documentation](/docs/editor/tasks-v1.md). + +--- + +Lots of tools exist to automate tasks like linting, building, packaging, testing or deploying software systems. Examples include the [TypeScript Compiler](https://www.typescriptlang.org/), linters like [ESLint](https://eslint.org/) and [TSLint](https://palantir.github.io/tslint/) as well as build systems like [Make](https://en.wikipedia.org/wiki/Make_software), [Ant](https://ant.apache.org/), [Gulp](https://gulpjs.com/), [Jake](http://jakejs.com/), [Rake](https://ruby.github.io/rake/) and [MSBuild](https://github.com/Microsoft/msbuild). + +![VS Code can talk to a variety of external tools](images/tasks/tasks_hero.png) + +These tools are mostly run from the command line and automate jobs inside and outside the inner software development loop (edit, compile, test, and debug). Given their importance in the development life-cycle, it is very helpful to be able to run tools and analyze their results from within VS Code. + +>**Note:** Task support is only available when working on a workspace folder. It is not available when editing single files. + +## TypeScript Hello World + +Let's start with a simple "Hello World" TypeScript program that we want to compile to JavaScript. + +Create an empty folder "mytask", generate a `tsconfig.json` file and start VS Code from that folder. + +```bash +mkdir mytask +cd mytask +tsc --init +code . +``` + +Now create a `HelloWorld.ts` file with the following content + +```ts +function sayHello(name: string): void { + console.log(`Hello ${name}!`); +} + +sayHello('Dave'); +``` + +Pressing `kb(workbench.action.tasks.build)` or running **Run Build Task** from the global **Terminal** menu show the following picker: + +![TypeScript Build Task](images/tasks/typescript-build.png) + +The first entry executes the TypeScript compiler and translates the TypeScript file to a JavaScript file. When the compiler has finished, there should be a `HelloWorld.js` file. The second entry starts the TypeScript compiler in watch mode. Every save to the `HelloWorld.ts` file will regenerate the `HelloWorld.js` file. + +You can also define the TypeScript build or watch task as the default build task so that it is executed directly when triggering **Run Build Task** (`kb(workbench.action.tasks.build)`). To do so, select **Configure Default Build Task** from the global **Terminal** menu. This shows you a picker with the available build tasks. Select **tsc: build** or **tsc: watch** and VS Code will generate a `tasks.json` file. The one shown below make the **tsc: build** task the default build task: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "type": "typescript", + "tsconfig": "tsconfig.json", + "problemMatcher": [ + "$tsc" + ], + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} +``` + +Unlike the previous `0.1.0` version of the `tasks.json` file, this does not define a new task. It annotates the **tsc: build** tasks contributed by VS Code's TypeScript extension to be the default build task. You can now execute the TypeScript compiler by pressing `kb(workbench.action.tasks.build)`. + +## Task auto-detection + +VS Code currently auto-detects tasks for the following systems: Gulp, Grunt, Jake and npm. We are working with the corresponding extension authors to add support for Maven and the C# `dotnet` command as well. If you develop a JavaScript application using Node.js as the runtime, you usually have a `package.json` file describing your dependencies and the scripts to run. If you have cloned the [eslint-starter](https://github.com/spicydonuts/eslint-starter) example, then executing **Run Tasks** from the global menu shows the following list: + +![Tasks ESLint starter](images/tasks/eslint-starter.png) + +If not done so install the necessary npm modules by running npm install. Now open the `server.js` file and add a semicolon to the end of a statement (note the ESLint starter assumes statements without a semicolon) and execute the **Run Tasks** again. This time select the **npm: lint** task. When prompted for the problem matcher to use, select **ESLint stylish** + +![Tasks ESLint Problem Matcher Selection](images/tasks/eslint-problem-matcher-selection.png) + +Executing the task produces one error shown in the **Problems** view: + +![Tasks ESLint Problem](images/tasks/eslint-problem.png) + +In addition, VS Code created a `tasks.json` file with the following content: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "type": "npm", + "script": "lint", + "problemMatcher": [ + "$eslint-stylish" + ] + } + ] +} +``` + +This instructs VS Code to scan the output of the **npm lint** script for problems using the ESLint stylish format. + +For Gulp, Grunt, and Jake, the task auto-detection works the same. Below is an example of the tasks detected for the [vscode-node-debug](https://github.com/Microsoft/vscode-node-debug) extension. + +![Gulp task auto-detection](images/tasks/gulp-auto-detect.png) + +>**Tip:** You can run your task through **Quick Open** (`kb(workbench.action.quickOpen)`) by typing 'task', `kbstyle(Space)` and the command name. In this case, 'task lint'. + +Task auto detection can be disabled using the following settings: + +```json +{ + "typescript.tsc.autoDetect": "off", + "grunt.autoDetect": "off", + "jake.autoDetect": "off", + "gulp.autoDetect": "off", + "npm.autoDetect": "off" +} +``` + +## Custom tasks + +Not all tasks or scripts can be auto-detected in your workspace. Sometimes it is necessary to define your own custom tasks. Assume you have a script to run your tests since it is necessary to setup some environment correctly. The script is stored in a script folder inside your workspace and named `test.sh` for Linux and macOS and `test.cmd` for Windows. Run **Configure Tasks** from the global **Terminal** menu and select the **Create tasks.json file from template** entry. This opens the following picker: + +![Configure Task Runner](images/tasks/configure-task-runner.png) + +>**Note:** If you don't see the list of task runner templates, you may already have a `tasks.json` file in your folder and its contents will be open in the editor. Close the file and either delete or rename it for this example. + +We are working on more auto-detection support, so this list will get smaller and smaller in the future. Since we want to write our own custom task, select **Others** from the list. This opens the `tasks.json` file with a task skeleton. Replace the contents with the following: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "Run tests", + "type": "shell", + "command": "./scripts/test.sh", + "windows": { + "command": ".\\scripts\\test.cmd" + }, + "group": "test", + "presentation": { + "reveal": "always", + "panel": "new" + } + } + ] +} +``` + +The task's properties have the following semantic: + +- **label**: The task's label used in the user interface. +- **type**: The task's type. For a custom task, this can either be `shell` or `process`. If `shell` is specified, the command is interpreted as a shell command (for example: bash, cmd, or PowerShell). If `process` is specified, the command is interpreted as a process to execute. +- **command**: The actual command to execute. +- **windows**: Any Windows specific properties. Will be used instead of the default properties when the command is executed on the Windows operating system. +- **group**: Defines to which group the task belongs. In the example, it belongs to the `test` group. Tasks that belong to the test group can be executed by running **Run Test Task** from the **Command Palette**. +- **presentation**: Defines how the task output is handled in the user interface. In this example, the Integrated Terminal showing the output is `always` revealed and a `new` terminal is created on every task run. +- **options**: Override the defaults for `cwd` (current working directory), `env` (environment variables), or `shell` (default shell). Options can be set per task but also globally or per platform. +- **runOptions**: Defines when and how a task is run. + +To see the full set of task properties and values, you can review the [tasks.json schema](/docs/editor/tasks-appendix.md). + +Shell commands need special treatment when it comes to commands and arguments that contains spaces or other special characters like `$`. By default the task system support the following behavior: + +* if a single command is provided the task system passes the command as is to the underlying shell. If the command needs quoting or escaping to function properly the command need to contain the proper quotes or escape characters. For example to list the directory of a folder containing spaces in its name the command executed in bash should look like this: `ls 'folder with spaces'`. +```json +{ + "label": "dir", + "type": "shell", + "command": "dir 'folder with spaces'" +} +``` +* if a command and arguments are provided the task system will use single quotes if the command or arguments contain spaces. For `cmd.exe` double quotes are used. So a shell command like below is executed in PowerShell as `dir 'folder with spaces'`. +```json +{ + "label": "dir", + "type": "shell", + "command": "dir", + "args": [ + "folder with spaces" + ] +} +``` +* if you want to control how the argument is quoted, the argument can be a literal specifying the value and a quoting style. Below an example that uses escaping instead of quoting for an argument with spaces. +```json +{ + "label": "dir", + "type": "shell", + "command": "dir", + "args": [ + { + "value": "folder with spaces", + "quoting": "escape" + } + ] +} +``` + +Besides escaping the following values are supported: + +* **strong**: Uses the shell's strong quoting mechanism which suppresses all evaluations inside the string. Under PowerShell and for shells under Linux and macOS, single quotes are used (`'`). For cmd.exe, `"` is used. +* **weak**: Uses the shell's weak quoting mechanism which still evaluates expression inside the string (e.g. for example environment variables). Under PowerShell and for shells under Linux and macOS, double quotes are used (`"`). cmd.exe doesn't support weak quoting so VS Code uses `"` as well. + +If the command itself contains spaces, VS Code will by default strong quote the command as well. As with arguments, the user can control the quoting of the command using the same literal style. + +There are more task properties to configure your workflow. You can use IntelliSense with `kb(editor.action.triggerSuggest)` to get an overview of the valid properties. + +![Tasks IntelliSense](images/tasks/intellisense.png) + +In addition to the global menu bar, task commands can be accessed using the **Command Palette** (`kb(workbench.action.showCommands)`). You can filter on 'task' and can see the various task related commands. + +![tasks in command palette](images/tasks/command-palette.png) + +### Compound tasks + +You can also compose tasks out of simpler tasks with the `dependsOn` property. For example, if you have a workspace with a client and server folder and both contain a build script, you can create a task that starts both build scripts in separate terminals. + +The `tasks.json` file looks like this: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Client Build", + "command": "gulp", + "args": ["build"], + "options": { + "cwd": "${workspaceRoot}/client" + } + }, + { + "label": "Server Build", + "command": "gulp", + "args": ["build"], + "options": { + "cwd": "${workspaceRoot}/server" + } + }, + { + "label": "Build", + "dependsOn": ["Client Build", "Server Build"] + } + ] +} +``` + +## Output behavior + +Sometimes you want to control how the Integrated Terminal panel behaves when running tasks. For instance, you may want to maximize editor space and only look at task output if you think there is a problem. The behavior of the terminal can be controlled using the `presentation` property of a task. It offers the following properties: + +- **reveal**: Controls whether the Integrated Terminal panel is brought to front. Valid values are: + - *always* - The panel is always brought to front. This is the default. + - *never* - The user must explicitly bring the terminal panel to the front using the **View** > **Terminal** command (`kb(workbench.action.terminal.toggleTerminal)`). + - *silent* - The terminal panel is brought to front only if the output is not scanned for errors and warnings. +- **focus**: Controls whether the terminal is taking input focus or not. Default is `false`. +- **echo**: Controls whether the executed command is echoed in the terminal. Default is `true`. +- **showReuseMessage**: Controls whether to show the "Terminal will be reused by tasks, press any key to close it" message. +- **panel**: Controls whether the terminal instance is shared between task runs. Possible values are: + - *shared*: The terminal is shared and the output of other task runs are added to the same terminal. + - *dedicated*: The terminal is dedicated to a specific task. If that task is executed again, the terminal is reused. However, the output of a different task is presented in a different terminal. + - *new*: Every execution of that task is using a new clean terminal. +- **clear**: Controls whether the terminal is cleared before this task is run. Default is `false`. +- **group**: Controls whether the task is executed in a specific terminal group using split panes. Tasks in the same group (specified by a string value) will use split terminals to present instead of a new terminal panel. + +You can modify the terminal panel behavior for auto-detected tasks as well. For example, if you want to change the output behavior for the **npm: run lint** from the ESLint example from above, add the `presentation` property to it: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "type": "npm", + "script": "lint", + "problemMatcher": [ + "$eslint-stylish" + ], + "presentation": { + "reveal": "never" + } + } + ] +} + +``` + +You can also mix custom tasks with configurations for detected tasks. A `tasks.json` that configures the **npm: run lint** task and adds a custom **Run Test** tasks looks like this: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "type": "npm", + "script": "lint", + "problemMatcher": [ + "$eslint-stylish" + ], + "presentation": { + "reveal": "never" + } + }, + { + "label": "Run tests", + "type": "shell", + "command": "./scripts/test.sh", + "windows": { + "command": ".\\scripts\\test.cmd" + }, + "group": "test", + "presentation": { + "reveal": "always", + "panel": "new" + } + } + ] +} + +``` + +## Run behavior + +You can specify a tasks run behaviors using the `runOptions` property: + +- **reevaluateOnRerun**: Controls how variables are evaluated whan a task is executed through the **Rerun Last Task** command. The default is `true`, meaning that variables will be re-evaluated when a task is rerun. When set to `false` the resolved variable values from the previous run of the task will be used. +- **runOn**: Specifies when a task is run. + - *default*: The task will only be run when executed through the **Run Task** command. + - *folderOpen*: The task will be run when the folder it is in is opened. The first time you open a folder that contains a task with *folderOpen* you will be asked if you allow tasks to run automatically in that folder. You can change you decision later using the **Allow Automatic Tasks in Folder** and **Disallow Automatic Tasks in Folder** commands. + +## Customizing auto-detected tasks + +As mentioned above, you can customize auto-detected tasks in the `tasks.json` file. You usually do so to modify presentation properties or to attach a problem matcher to scan the task's output for errors and warnings. You can customize a task directly from the **Run Task** list by pressing the gear icon to the right to insert the corresponding task reference into the `tasks.json` file. Assume you have the following Gulp file to lint JavaScript files using ESLint (the file is taken from https://github.com/adametry/gulp-eslint): + +```js +const gulp = require('gulp'); +const eslint = require('gulp-eslint'); + +gulp.task('lint', () => { + // ESLint ignores files with "node_modules" paths. + // So, it's best to have gulp ignore the directory as well. + // Also, Be sure to return the stream from the task; + // Otherwise, the task may end before the stream has finished. + return gulp.src(['**/*.js','!node_modules/**']) + // eslint() attaches the lint output to the "eslint" property + // of the file object so it can be used by other modules. + .pipe(eslint()) + // eslint.format() outputs the lint results to the console. + // Alternatively use eslint.formatEach() (see Docs). + .pipe(eslint.format()) + // To have the process exit with an error code (1) on + // lint error, return the stream and pipe to failAfterError last. + .pipe(eslint.failAfterError()); +}); + +gulp.task('default', ['lint'], function () { + // This will only run if the lint task is successful... +}); +``` + +Executing **Run Task** from the global **Terminal** menu will show the following picker: + +![Configure Task](images/tasks/configure-tasks.png) + +Press the gear icon. This will create the following `tasks.json` file: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "type": "gulp", + "task": "default", + "problemMatcher": [] + } + ] +} +``` + +Usually you would now add a problem matcher (in this case `$eslint-stylish`) or modify the presentation settings. + +## Processing task output with problem matchers + +VS Code can process the output from a task with a problem matcher and ships with several problem matchers 'in-the-box': + +- **TypeScript**: `$tsc` assumes that file names in the output are relative to the opened folder. +- **TypeScript Watch**: `$tsc-watch` matches problems reported from the `tsc` compiler when executed in watch mode. +- **JSHint**: `$jshint` assumes that file names are reported as an absolute path. +- **JSHint Stylish**: `$jshint-stylish` assumes that file names are reported as an absolute path. +- **ESLint Compact**: `$eslint-compact` assumes that file names in the output are relative to the opened folder. +- **ESLint Stylish**: `$eslint-stylish` assumes that file names in the output are relative to the opened folder. +- **Go**: `$go` matches problems reported from the `go` compiler. Assumes that file names are relative to the opened folder. +- **CSharp and VB Compiler**: `$mscompile` assumes that file names are reported as an absolute path. +- **Lessc compiler**: `$lessc` assumes that file names are reported as absolute path. +- **Node Sass compiler**: `$node-sass` assumes that file names are reported as an absolute path. + +Problem matchers scan the task output text for known warning or error strings and report these inline in the editor and in the Problems panel. + +You can also create your own problem matcher which we'll discuss [in a later section](/docs/editor/tasks.md#defining-a-problem-matcher). + +## Binding keyboard shortcuts to tasks + +If you need to run a task frequently, you can define a keyboard shortcut for the task. + +For example, to bind `Ctrl+H` to the **Run tests** task from above, add the following to your `keybindings.json` file: + +```json +{ + "key": "ctrl+h", + "command": "workbench.action.tasks.runTask", + "args": "Run tests" +} +``` + +## Variable substitution + +When authoring tasks configurations, it is useful to have a set of predefined common variables such as the active file (`${file}`) or workspace root folder (`${workspaceFolder}`). VS Code supports variable substitution inside strings in the `tasks.json` file and you can see a full list of predefined variables in the [Variables Reference](/docs/editor/variables-reference.md). + +Below is an example of a custom task configuration that passes the current opened file to the TypeScript compiler. + +```json +{ + "label": "TypeScript compile", + "type": "shell", + "command": "tsc ${file}", + "problemMatcher": [ + "$tsc" + ] +} +``` + +Similarly, you can reference your project's configuration settings by prefixing the name with **${config:**. For example, `${config:python.pythonPath}` returns the Python extension setting `pythonPath`. + +Below is an example of a custom task configuration which executes autopep8 on the current file using your project's selected Python executable: + +```json +{ + "label": "autopep8 current file", + "type": "process", + "command": "${config:python.pythonPath}", + "args": [ + "-m", + "autopep8", + "-i", + "${file}" + ] +} +``` + +If simple variable substitution isn't enough, you can also get input from the user of your task by adding an `inputs` section to your `tasks.json` file. + +![Inputs Example](images/tasks/run-input-example.gif) + +For more information about `inputs` see the [Variables Reference](/docs/editor/variables-reference.md). + +## Operating system specific properties + +The task system supports defining values (for example, the command to be executed) specific to an operating system. To do so, put an operating system specific literal into the `tasks.json` file and specify the corresponding properties inside that literal. + +Below is an example that uses the Node.js executable as a command and is treated differently on Windows and Linux: + +```json +{ + "label": "Run Node", + "type": "process", + "windows": { + "command": "C:\\Program Files\\nodejs\\node.exe" + }, + "linux": { + "command": "/usr/bin/node" + } +} +``` + +Valid operating properties are `windows` for Windows, `linux` for Linux, and `osx` for macOS. Properties defined in an operating system specific scope override properties defined in the task or global scope. + +Task properties can also be defined in the global scope. If present, they will be used for specific tasks unless they define the same property with a different value. In the example below, there is a global `presentation` property that defines that all tasks should be executed in a new panel: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "presentation": { + "panel": "new" + }, + "tasks": [ + { + "label": "TS - Compile current file", + "type": "shell", + "command": "tsc ${file}", + "problemMatcher": [ + "$tsc" + ] + } + ] +} +``` + +## Changing the encoding for a task output + +Tasks frequently act with files on disk. If these files are stored on disk with an encoding different than the system encoding you need to let the command executed as a task know which encoding to use. Since this depends on the operating system and the shell used there is no general solution to control this. Below some advice and examples on how to make it work. + +If you need to tweak the encoding you should check whether it makes sense to change the default encoding used by our operating system or at least changing it for the shell you use by tweaking the shell's profile file. + +If you only need to tweak it for a specific task then add the OS specific command necessary to change the encoding to the tasks command line. The following example is for Windows using code page of 437 as its default. The task shows the output of a file containing Cyrillic characters and therefore needs code page 866. The task to list the file looks like this assuming that the default shell is set to `cmd.exe`: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "more", + "type": "shell", + "command": "chcp 866 && more russian.txt", + "problemMatcher": [] + } + ] +} +``` + +If the task is execute in `PowerShell`, the command needs to read like this `chcp 866; more russian.txt`. On Linux and macOS, the `locale` command can be used to inspect the locale and tweak the necessary environment variables. + +## Examples of tasks in action + +To highlight the power of tasks, here are a few examples of how VS Code can use tasks to integrate external tools like linters and compilers. + +### Transpiling TypeScript to JavaScript + +The [TypeScript topic](/docs/languages/typescript.md#transpiling-typescript-into-javascript) includes an example that creates a task to transpile TypeScript to JavaScript and observe any related errors from within VS Code. + +### Compiling Markdown to HTML + +The Markdown topic provides two examples for compiling Markdown to HTML: + +1. [Manually compiling with a Build task](/docs/languages/markdown.md#compiling-markdown-into-html) +2. [Automating the compile step with a file watcher](/docs/languages/markdown.md#automating-markdown-compilation) + +### Transpiling Less and SCSS into CSS + +The CSS topic provides examples of how to use Tasks to generate CSS files. + +1. [Manually transpiling with a Build task](/docs/languages/css.md#transpiling-sass-and-less-into-css) +2. [Automation of the compile step with a file watcher](/docs/languages/css.md#automating-sassless-compilation) + +## Defining a problem matcher + +VS Code ships some of the most common problem matchers 'in-the-box'. However, there are lots of compilers and linting tools out there, all of which produce their own style of errors and warnings so you may want to create your own problem matcher. + +We have a `helloWorld.c` program in which the developer mistyped **printf** as **prinft**. Compiling it with [gcc](https://gcc.gnu.org/) will produce the following warning: + +```bash +helloWorld.c:5:3: warning: implicit declaration of function ‘prinft’ +``` + +We want to produce a problem matcher that can capture the message in the output and show a corresponding problem in VS Code. Problem matchers heavily rely on [regular expressions](https://en.wikipedia.org/wiki/Regular_expression). The section below assumes you are familiar with regular expressions. + +>**Tip:** We have found the [RegEx101 playground](https://regex101.com/) to be a great way to develop and test regular expressions. + +A matcher that captures the above warning (and errors) looks like this: + +```json +{ + // The problem is owned by the cpp language service. + "owner": "cpp", + // The file name for reported problems is relative to the opened folder. + "fileLocation": ["relative", "${workspaceFolder}"], + // The actual pattern to match problems in the output. + "pattern": { + // The regular expression. Example to match: helloWorld.c:5:3: warning: implicit declaration of function ‘printf’ [-Wimplicit-function-declaration] + "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$", + // The first match group matches the file name which is relative. + "file": 1, + // The second match group matches the line on which the problem occurred. + "line": 2, + // The third match group matches the column at which the problem occurred. + "column": 3, + // The fourth match group matches the problem's severity. Can be ignored. Then all problems are captured as errors. + "severity": 4, + // The fifth match group matches the message. + "message": 5 + } +} +``` + +Please note that the file, line and message properties are mandatory. + +Here is a finished `tasks.json` file with the code above (comments removed) wrapped with the actual task details: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "build", + "command": "gcc", + "args": ["-Wall", "helloWorld.c", "-o", "helloWorld"], + "problemMatcher": { + "owner": "cpp", + "fileLocation": ["relative", "${workspaceFolder}"], + "pattern": { + "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$", + "file": 1, + "line": 2, + "column": 3, + "severity": 4, + "message": 5 + } + } + } + ] +} +``` + +Running it inside VS Code and pressing `kb(workbench.actions.view.problems)` to get the list of problems gives you the following output: + +![GCC Problem Matcher](images/tasks/problemmatcher.png) + +>**Note:** The [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) includes problem matchers for GCC so there is no need to define our own. + +There are a couple more properties that can be used inside a pattern. These are: + +- **location** if the problem location is line or line,column or startLine,startColumn,endLine,endColumn then our generic location match group can be used. +- **endLine** the match group index for the problem's end line. Can be omitted if no end line value is provided by the compiler. +- **endColumn** the match group index for the problem's end column. Can be omitted if no end column value is provided by the compiler. +- **code** the match group index for the problem's code. Can be omitted if no code value is provided by the compiler. + +You can also define a problem matcher that captures only a file. To do so, define a `pattern` with the optional `kind` attribute set to `file`. In this case, there is no need to provide a `line` or `location` property. + +>**Note:** A functional pattern must at least provide a match group for `file` and `message` if the `kind` property is set to `file`. If no `kind` property is provided or the `kind` property is set to `location`, a function pattern must provide a `line` or `location` property as well. + +## Defining a multiline problem matcher + +Some tools spread problems found in a source file over several lines, especially if stylish reporters are used. An example is [ESLint](https://eslint.org/); in stylish mode it produces output like this: + +```bash +test.js + 1:0 error Missing "use strict" statement strict +✖ 1 problems (1 errors, 0 warnings) +``` + +Our problem matcher is line-based so we need to capture the file name (test.js) with a different regular expression than the actual problem location and message (1:0 error Missing "use strict" statement). + +To do this we use an array of problem patterns for the `pattern` property. This way you define a pattern per each line you want to match. + +The following problem pattern matches the output from ESLint in stylish mode - but still has one small issue which we will resolve next. The code below has a first regular expression to capture the file name and the second to capture the line, column, severity, message and error code: + +```json +{ + "owner": "javascript", + "fileLocation": ["relative", "${workspaceFolder}"], + "pattern": [ + { + "regexp": "^([^\\s].*)$", + "file": 1 + }, + { + "regexp": "^\\s+(\\d+):(\\d+)\\s+(error|warning|info)\\s+(.*)\\s\\s+(.*)$", + "line": 1, + "column": 2, + "severity": 3, + "message": 4, + "code": 5 + } + ] +} +``` + +However, this pattern will not work if there is more than one problem on a resource. For instance, imagine the following output from ESLint: + +```bash +test.js + 1:0 error Missing "use strict" statement strict + 1:9 error foo is defined but never used no-unused-vars + 2:5 error x is defined but never used no-unused-vars + 2:11 error Missing semicolon semi + 3:1 error "bar" is not defined no-undef + 4:1 error Newline required at end of file but not found eol-last +✖ 6 problems (6 errors, 0 warnings) +``` + +The pattern's first regular expression will match "test.js", the second "1:0 error ...". The next line "1:9 error ..." is processed but not matched by the first regular expression and so no problem is captured. + +To make this work, the last regular expression of a multiline pattern can specify the `loop` property. If set to true, it instructs the task system to apply the last pattern of a multiline matcher to the lines in the output as long as the regular expression matches. + +The information captured by all previous patterns is combined with the information captured by the last pattern and turned into a problem inside VS Code. + +Here is a problem matcher to fully capture ESLint stylish problems: + +```json +{ + "owner": "javascript", + "fileLocation": ["relative", "${workspaceFolder}"], + "pattern": [ + { + "regexp": "^([^\\s].*)$", + "file": 1 + }, + { + "regexp": "^\\s+(\\d+):(\\d+)\\s+(error|warning|info)\\s+(.*)\\s\\s+(.*)$", + "line": 1, + "column": 2, + "severity": 3, + "message": 4, + "code": 5, + "loop": true + } + ] +} +``` + +## Background / watching tasks + +Some tools support running in the background while watching the file system for changes and then triggering an action when a file changes on disk. With `Gulp` such functionality is provided through the npm module [gulp-watch](https://www.npmjs.com/package/gulp-watch). The TypeScript compiler `tsc` has built in support for this via the `--watch command` line option. + +To provide feedback that a background task is active in VS Code and producing problem results, a problem matcher has to use additional information to detect these `state` changes in the output. Let's take the `tsc` compiler as an example. When the compiler is started in watch mode, it prints the following additional information to the console: + +``` +> tsc --watch +12:30:36 PM - Compilation complete. Watching for file changes. +``` + +When a file changes on disk which contains a problem, the following output appears: + +``` +12:32:35 PM - File change detected. Starting incremental compilation... +src/messages.ts(276,9): error TS2304: Cannot find name 'candidate'. +12:32:35 PM - Compilation complete. Watching for file changes. +``` + +Looking at the output shows the following pattern: + +- The compiler runs when `File change detected. Starting incremental compilation...` is printed to the console. +- The compiler stops when `Compilation complete. Watching for file changes.` is printed to the console. +- Between those two strings problems are reported. +- The compiler also runs once the initial start (without printing `File change detected. Starting incremental compilation...` to the console). + +To capture this information, a problem matcher can provide a `background` property. + +For the `tsc` compiler, an appropriate `background` property looks like this: + +```json +"background": { + "activeOnStart": true, + "beginsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - File change detected\\. Starting incremental compilation\\.\\.\\.", + "endsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - Compilation complete\\. Watching for file changes\\." +} +``` + +In addition to the `background` property on the problem matcher, the task itself has to be marked as `isBackground` so that the task keeps running in the background. + +A full handcrafted `tasks.json` for a `tsc` task running in watch mode looks like this: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "watch", + "command": "tsc", + "args": ["--watch"], + "isBackground": true, + "problemMatcher": { + "owner": "typescript", + "fileLocation": "relative", + "pattern": { + "regexp": "^([^\\s].*)\\((\\d+|\\d+,\\d+|\\d+,\\d+,\\d+,\\d+)\\):\\s+(error|warning|info)\\s+(TS\\d+)\\s*:\\s*(.*)$", + "file": 1, + "location": 2, + "severity": 3, + "code": 4, + "message": 5 + }, + "background": { + "activeOnStart": true, + "beginsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - File change detected\\. Starting incremental compilation\\.\\.\\.", + "endsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - Compilation complete\\. Watching for file changes\\." + } + } + } + ] +} +``` + +## Convert from "0.1.0" to "2.0.0" + +**Note**: If you have created a workspace that consists of multiple folders ([Multi-root Workspace](/docs/editor/multi-root-workspaces.md)), only version `2.0.0` tasks are detected and shown in the **Terminal** > **Run Task** picker. + +### Try running without tasks.json + +Tasks `2.0.0` version comes with lots of new auto-detection features so you can try removing an existing `tasks.json` file to see which tasks still work. One way is to rename the existing `tasks.json` to `tasks.json.off`. + +### Migrating to Tasks 2.0.0 + +If you have lots of task customizations then you can switch by changing the version attribute to `"2.0.0"`. After doing so, you might encounter warnings (green squiggles) because some properties are now deprecated. + +Here is a migration guide: + +- **taskName**: Use the `label` property instead. +- **isShellCommand**: Use the `"type": "shell"` property instead. +- **isBuildCommand**: Use the `"group": "build"` property instead. +- **isTestCommand**: Use the `"group": "test"` property instead. +- **echoCommand**: Use the `"presentation" : { "echo": "..." }` property instead. +- **showOutput**: Use the `"presentation" : { "reveal": "..." }` property instead. +- **suppressTaskName**: By default, the task name gets appended to the list of arguments when running a task version `0.1.0`. Since version `2.0.0` supports commands per task, you can inline the command into the task and specify the arguments accordingly. + +Consider the following `0.1.0` configuration: + +```json +{ + "version": "0.1.0", + "isShellCommand": true, + "command": "script", + "tasks": [ + { + "taskName": "Run tests", + "suppressTaskName": true, + "args": [ + "test" + ] + } + ] +} +``` + +The corresponding `2.0.0` configuration would look like this: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Run tests", + "type": "shell", + "command": "script test" + } + ] +} +``` + +- **taskSelector**: Move the command into the task and specify the task selector inside the command. + +```json +{ + "version": "0.1.0", + "command": "msbuild", + "args": [ + "/property:GenerateFullPaths=true" + ], + "taskSelector": "/t:", + "tasks": [ + { + "label": "build" + } + ] +} +``` + +A corresponding `2.0.0` configuration would look like this: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "build", + "command": "msbuild", + "args": [ + "/property:GenerateFullPaths=true", + "/t:build" + ] + } + ] +} +``` + +If you want to use a `0.1.0` version of the `tasks.json` file with the new terminal runner, you can add the `runner` property to the `tasks.json` file: `"runner": "terminal"`. + +## Next steps + +That was tasks - let's keep going... + +* [tasks.json Schema](/docs/editor/tasks-appendix.md) - You can review the full `tasks.json` schema and descriptions. +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Language Support](/docs/languages/overview.md) - Learn about our supported programming languages, both shipped with VS Code and through community extensions. +* [Debugging](/docs/editor/debugging.md) - Debug your source code directly in the VS Code editor. + +## Common questions + +### Can a task use a different shell than the one specified for the Integrated Terminal? + +You can override a task's shell with the `options.shell` property. You can set this per task, globally, or per platform. For example, to use cmd.exe on Windows, your `tasks.json` would include: + +```json +{ + "version": "2.0.0", + "windows": { + "options": { + "shell": { + "executable": "cmd.exe", + "args": [ + "/d", "/c" + ] + } + } + }, + ... +``` diff --git a/docs/editor/userdefinedsnippets.md b/docs/editor/userdefinedsnippets.md new file mode 100644 index 0000000000000000000000000000000000000000..abc444e06240931828411e594ae827b88098555d --- /dev/null +++ b/docs/editor/userdefinedsnippets.md @@ -0,0 +1,267 @@ +--- +Order: 12 +Area: editor +TOCTitle: Creating snippets +ContentId: 79CD9B45-97FF-48B1-8DD5-2555F56206A6 +PageTitle: Creating your own snippets in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: It is easy to add code snippets to Visual Studio Code both for your own use or to share with others on the public Extension Marketplace. TextMate .tmSnippets files are supported. +--- +# Creating your own snippets + +Code snippets are templates that make it easier to enter repeating code patterns, such as loops or conditional-statements. + +In Visual Studio Code, snippets show in IntelliSense (`kb(editor.action.triggerSuggest)`) mixed with other suggestions as well as in a dedicated snippet picker (**Insert Snippet** in the Command Palette). There is also support for tab-completion: Enable it with `"editor.tabCompletion": "on"`, type a *snippet prefix*, and press `kb(insertSnippet)` to insert a snippet. + +The snippet syntax follows the [TextMate snippet syntax](https://manual.macromates.com/en/snippets) with the exceptions of 'interpolated shell code' and the use of `\u`; both are not supported. + +![ajax snippet](images/userdefinedsnippets/ajax-snippet.gif) + +## Add snippets from the Marketplace + +Many [extensions](/docs/editor/extension-gallery.md) on the VS Code [Marketplace](https://marketplace.visualstudio.com/vscode) include snippets. If you find one you want to use, install it and restart VS Code and the new snippet will be available (see [here](/docs/editor/extension-gallery.md#browse-and-install-extensions) for more instructions on installing an extension). + +Below are some popular extensions which include snippets in their language support: + +
+ +> **Tip**: The extensions shown above are dynamically queried. Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com/vscode). + +## Creating your own snippets + +You can define your own snippets, either global snippets or snippets for a specific language. To open up a snippet file for editing, select **User Snippets** under **File** > **Preferences** (**Code** > **Preferences** on macOS) and select the language (by [language identifier](/docs/languages/identifiers.md)) for which the snippets should appear or create a new global snippet (**New Global Snippets file**). + +![snippet drop-down](images/userdefinedsnippets/snippet-dropdown.png) + +Snippets are defined in a JSON format. The example below is a `For Loop` snippet you would use for JavaScript: + +```json +{ + "For_Loop": { + "prefix": "for", + "body": [ + "for (const ${2:element} of ${1:array}) {", + "\t$0", + "}" + ], + "description": "For Loop" + } +} +``` + +In the example above: + +* `For Loop` is the snippet name. +* `prefix` defines how this snippet is selected from IntelliSense and tab completion. In this case `for`. +* `body` is the content and either a single string or an array of strings of which each element will be inserted as separate line. +* `description` is the description used in the IntelliSense drop down. + +The example above has two placeholders, `${1:array}` and `${2:element}`. You can quickly traverse them in the order of their number. The string after the number and colon is used as an initial default. + +### Snippet filenames + +The file type and name define if a snippet is global or specific to a language. Snippets stored in a JSON file that is named after a [language identifier](/docs/languages/identifiers.md) (`.json`) are language specific. For example, JavaScript-only snippets go in a `javascript.json` file. + +### Global snippets + +Global snippets that are applicable whenever you are editing and are stored in `.code-snippets` files, for example `MyGlobal.code-snippets`. The JSON schema of global snippets allows you to define a `scope` property which can filter the languages (based on [language identifier](/docs/languages/identifiers.md)) for which a snippet is applicable. + +The sample below is the `For Loop` again but this time it is scoped to JavaScript *and* TypeScript. + +```json +{ + "For_Loop": { + "prefix": "for", + "scope": "javascript,typescript", + "body": [ + "for (const ${2:element} of ${1:array}) {", + "\t$0", + "}" + ], + "description": "For Loop" + } +} +``` + +Once you have added a new snippet, you can try it out right away, no restart needed. + +## Snippet syntax + +The `body` of a snippet can use special constructs to control cursors and the text being inserted. The following are supported features and their syntaxes: + +### Tabstops + +With tabstops, you can make the editor cursor move inside a snippet. Use `$1`, `$2` to specify cursor locations. The number is the order in which tabstops will be visited, whereas `$0` denotes the final cursor position. Multiple occurrences of the same tabstop are linked and updated in sync. + +### Placeholders + +Placeholders are tabstops with values, like `${1:foo}`. The placeholder text will be inserted and selected such that it can be easily changed. Placeholders can be nested, like `${1:another ${2:placeholder}}`. + +### Choice + +Placeholders can have choices as values. The syntax is a comma separated enumeration of values, enclosed with the pipe-character, for example `${1|one,two,three|}`. When the snippet is inserted and the placeholder selected, choices will prompt the user to pick one of the values. + +### Variables + +With `$name` or `${name:default}` you can insert the value of a variable. When a variable isn’t set, its *default* or the empty string is inserted. When a variable is unknown (that is, its name isn’t defined) the name of the variable is inserted and it is transformed into a placeholder. + +The following variables can be used: + +* `TM_SELECTED_TEXT` The currently selected text or the empty string +* `TM_CURRENT_LINE` The contents of the current line +* `TM_CURRENT_WORD` The contents of the word under cursor or the empty string +* `TM_LINE_INDEX` The zero-index based line number +* `TM_LINE_NUMBER` The one-index based line number +* `TM_FILENAME` The filename of the current document +* `TM_FILENAME_BASE` The filename of the current document without its extensions +* `TM_DIRECTORY` The directory of the current document +* `TM_FILEPATH` The full file path of the current document +* `CLIPBOARD` The contents of your clipboard + +For inserting the current date and time: + +* `CURRENT_YEAR` The current year +* `CURRENT_YEAR_SHORT` The current year's last two digits +* `CURRENT_MONTH` The month as two digits (example '02') +* `CURRENT_MONTH_NAME` The full name of the month (example 'July') +* `CURRENT_MONTH_NAME_SHORT` The short name of the month (example 'Jul') +* `CURRENT_DATE` The day of the month +* `CURRENT_DAY_NAME` The name of day (example 'Monday') +* `CURRENT_DAY_NAME_SHORT` The short name of the day (example 'Mon') +* `CURRENT_HOUR` The current hour in 24-hour clock format +* `CURRENT_MINUTE` The current minute +* `CURRENT_SECOND` The current second + +For inserting line or block comments, honoring the current language: + +* `BLOCK_COMMENT_START` Example output: in PHP `/*` or in HTML `` +* `LINE_COMMENT` Example output: in PHP `//` or in HTML `` + +The snippet below inserts `/* Hello World */` in JavaScript files and `` in HTML files: + +```json +{ + "hello": { + "scope": "javascript,html", + "prefix": "hello", + "body": "$BLOCK_COMMENT_START Hello World $BLOCK_COMMENT_END" + } +} +``` + +### Variable transforms + +Transformations allow you to modify the value of a variable before it is inserted. The definition of a transformation consists of three parts: + +1. A regular expression that is matched against the value of a variable, or the empty string when the variable cannot be resolved. +2. A "format string" that allows to reference matching groups from the regular expression. The format string allows for conditional inserts and simple modifications. +3. Options that are passed to the regular expression. + +The following example inserts the name of the current file without its ending, so from `foo.txt` it makes `foo`. + +``` +${TM_FILENAME/(.*)\\..+$/$1/} + | | | | + | | | |-> no options + | | | + | | |-> references the contents of the first + | | capture group + | | + | |-> regex to capture everything before + | the final `.suffix` + | + |-> resolves to the filename +``` + +### Placeholder-Transform + +Like a Variable-Transform, a transformation of a placeholder allows changing the inserted text for the placeholder when moving to the next tab stop. +The inserted text is matched with the regular expression and the match or matches - depending on the options - are replaced with the specified replacement format text. +Every occurrence of a placeholder can define its own transformation independently using the value of the first placeholder. +The format for Placeholder-Transforms is the same as for Variable-Transforms. + +### Transform examples + +The examples are shown within double quotes, as they would appear inside a snippet body, to illustrate the need to double escape certain characters. Sample transformations and the resulting output for the filename `example-123.456-TEST.js`. + +Example | Output | Explanation +-------------|--------|------------ +`"${TM_FILENAME/[\\.]/_/}"` | `example-123_456-TEST.js` | Replace the first `.` with `_` +`"${TM_FILENAME/[\\.-]/_/g}"` | `example_123_456_TEST_js` | Replace each `.` or `-` with `_` +`"${TM_FILENAME/(.*)/${1:/upcase}/}"` | `EXAMPLE-123.456-TEST.JS` | Change to all uppercase +`"${TM_FILENAME/[^0-9^a-z]//gi}"` | `example123456TESTjs` | Remove non-alphanumeric characters + +### Grammar + +Below is the EBNF ([extended Backus-Naur form](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form)) for snippets. With `\` (backslash), you can escape `$`, `}` and `\`. Within choice elements, the backslash also escapes comma and pipe characters. + +``` +any ::= tabstop | placeholder | choice | variable | text +tabstop ::= '$' int + | '${' int '}' + | '${' int transform '}' +placeholder ::= '${' int ':' any '}' +choice ::= '${' int '|' text (',' text)* '|}' +variable ::= '$' var | '${' var '}' + | '${' var ':' any '}' + | '${' var transform '}' +transform ::= '/' regex '/' (format | text)+ '/' options +format ::= '$' int | '${' int '}' + | '${' int ':' '/upcase' | '/downcase' | '/capitalize' '}' + | '${' int ':+' if '}' + | '${' int ':?' if ':' else '}' + | '${' int ':-' else '}' | '${' int ':' else '}' +regex ::= JavaScript Regular Expression value (ctor-string) +options ::= JavaScript Regular Expression option (ctor-options) +var ::= [_a-zA-Z] [_a-zA-Z0-9]* +int ::= [0-9]+ +text ::= .* +``` + +## Using TextMate snippets + +You can also use existing TextMate snippets (.tmSnippets) with VS Code. See the [Using TextMate Snippets](/api/language-extensions/snippet-guide.md#using-textmate-snippets) topic in our Extension API section to learn more. + +## Assign keybindings to snippets + +You can create custom [keybindings](/docs/getstarted/keybindings.md) to insert specific snippets. Open `keybindings.json` (**Preferences: Open Keyboard Shortcuts File**), which defines all your keybindings, and add a keybinding passing `"snippet"` as an extra argument: + +```json +{ + "key": "cmd+k 1", + "command": "editor.action.insertSnippet", + "when": "editorTextFocus", + "args": { + "snippet": "console.log($1)$0" + } +} +``` + +The keybinding will invoke the **Insert Snippet** command but instead of prompting you to select a snippet, it will insert the provided snippet. You define the custom [keybinding](/docs/getstarted/keybindings.md) as usual with a keyboard shortcut, command id, and optional [when clause context](/docs/getstarted/keybindings.md#when-clause-contexts) for when the keyboard shortcut is enabled. + +Also, instead of using the `snippet` argument value to define your snippet inline, you can reference an existing snippet by using the `langId` and `name` arguments : + +```json +{ + "key": "cmd+k 1", + "command": "editor.action.insertSnippet", + "when": "editorTextFocus", + "args": { + "langId": "csharp", + "name": "myFavSnippet" + } +} +``` + +## Next steps + +* [Command Line](/docs/editor/command-line.md) - VS Code has a rich command line interface to open or diff files and install extensions. +* [Extension API](/api) - Learn about other ways to extend VS Code. +* [Snippet Guide](/api/language-extensions/snippet-guide.md) - You can package snippets for use in VS Code. + +## Common questions + +### What if I want to use existing TextMate snippets from a .tmSnippet file? + +You can easily package TextMate snippets files for use in VS Code. See [Using TextMate Snippets](/api/language-extensions/snippet-guide.md#using-textmate-snippets) in our Extension API documentation. diff --git a/docs/editor/variables-reference.md b/docs/editor/variables-reference.md new file mode 100644 index 0000000000000000000000000000000000000000..91441c640b63460fcc88e4d800b615a800facb0f --- /dev/null +++ b/docs/editor/variables-reference.md @@ -0,0 +1,249 @@ +--- +Order: +Area: editor +TOCTitle: Variables reference +ContentId: ff9cd4ea-e3f0-4170-9451-2f2ea2b909ea +PageTitle: Visual Studio Code Variables Reference +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code variable substitution reference +--- +# Variables Reference + +Visual Studio Code supports variable substitution in [Debugging](/docs/editor/debugging.md) and [Task](/docs/editor/tasks.md) configuration files. Variable substitution is supported inside key and value strings in `launch.json` and `tasks.json` files using **${variableName}** syntax. + +## Predefined variables + +The following predefined variables are supported: + +- **${workspaceFolder}** - the path of the folder opened in VS Code +- **${workspaceFolderBasename}** - the name of the folder opened in VS Code without any slashes (/) +- **${file}** - the current opened file +- **${relativeFile}** - the current opened file relative to `workspaceFolder` +- **${fileBasename}** - the current opened file's basename +- **${fileBasenameNoExtension}** - the current opened file's basename with no file extension +- **${fileDirname}** - the current opened file's dirname +- **${fileExtname}** - the current opened file's extension +- **${cwd}** - the task runner's current working directory on startup +- **${lineNumber}** - the current selected line number in the active file +- **${selectedText}** - the current selected text in the active file +- **${execPath}** - the path to the running VS Code executable + +### Predefined variables examples + +Supposing that you have the following requirements: + +1. A file located at `/home/your-username/your-project/folder/file.ext` opened in your editor; +2. The directory `/home/your-username/your-project` opened as your root workspace. + +So you will have the following values for each variable: + +- **${workspaceFolder}** - `/home/your-username/your-project` +- **${workspaceFolderBasename}** - `your-project` +- **${file}** - `/home/your-username/your-project/folder/file.ext` +- **${relativeFile}** - `folder/file.ext` +- **${fileBasename}** - `file.ext` +- **${fileBasenameNoExtension}** - `file` +- **${fileDirname}** - `/home/your-username/your-project/folder` +- **${fileExtname}** - `.ext` +- **${lineNumber}** - line number of the cursor +- **${selectedText}** - text selected in your code editor +- **${execPath}** - location of Code.exe + +>**Tip**: Use IntelliSense inside string values for `tasks.json` and `launch.json` to get a full list of predefined variables. + +### Variables scoped per workspace folder + +By appending the root folder's name to a variable (separated by a colon), it is possible to reach into sibling root folders of a workspace. Without the root folder name, the variable is scoped to the same folder where it is used. + +For example, in a multi root workspace with folders `Server` and `Client`, a `${workspaceFolder:Client}` refers to the path of the `Client` root. + +## Environment variables + +You can also reference environment variables through the **${env:Name}** syntax (for example, `${env:PATH}`). + +```json +{ + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${workspaceFolder}/app.js", + "cwd": "${workspaceFolder}", + "args": [ "${env:USERNAME}" ] +} +``` + +**Note**: Be sure to match the environment variable name's casing, for example `${env:Path}` on Windows. + +## Configuration variables + +You can reference VS Code settings (aka "configurations") through **${config:Name}** syntax (for example, `${config:editor.fontSize}`). + +## Command variables + +If the predefined variables from above are not sufficient, you can use any VS Code command as a variable through the **${command:commandID}** syntax. + +When a command variable is interpolated, the command is run and the variable is substituted by the command's (string) result. The implementation of a command can range from a simple calculation with no UI, to some sophisticated functionality based on the UI features available via VS Code's extension API. + +An example for this functionality can be found in VS Code's Node.js debugger extension which provides an interactive command `extension.pickNodeProcess` for selecting a single process from the list of all running Node.js processes. The command returns the process ID of the selected process. This makes it possible to use the `extension.pickNodeProcess` command in an **Attach by Process ID** launch configuration in the following way: + +```json +{ + "configurations": [ + { + "type": "node", + "request": "attach", + "name": "Attach by Process ID", + "processId": "${command:extension.pickNodeProcess}" + } + ] +} +``` + +## Input variables + +Command variables are already powerful but they lack a mechanism to configure the command being run to a specific use case. E.g. it is not possible to pass a *prompt message* or a *default value* to a generic "user input prompt". + +This limitation is solved with **input variables** which have the syntax: `${input:variableID}`. The `variableID` refers to entries in the "inputs" section of launch.json and tasks.json, where additional configuration attributes are specified. + +The following example shows the overall structure of a `task.json` that makes use of input variables: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "task name", + "command": "${input:variableID}", + // ... + } + ], + "inputs": [ + { + "id": "variableID", + "type": "type of input variable", + // type specific configuration attributes + } + ] +} +``` + +Currently VS Code supports three types of input variables: + +- **promptString**: Shows an input box to get a string from the user. +- **pickString**: Shows a Quick Pick dropdown to let the user select from several options. +- **command**: Runs an arbitrary command. + +Each type requires additional configuration attributes: + +`promptString`: + +- **description**: Shown in the quick input provides context for the input. +- **default**: Default value that will be used if the user doesn't enter something else. + +`pickString`: + +- **description**: Shown in the quick pick provides context for the input. +- **options**: An array of options for the user to pick from. +- **default**: Default value that will be used if the user doesn't enter something else. It must be one of the option values. + +`Command`: + +- **command**: Command being run on variable interpolation. +- **args**: Optional option bag passed to the command's implementation. + + +Below is an example of a `tasks.json` that illustrates the use of `inputs` using Angular CLI: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "ng g", + "type": "shell", + "command": "ng", + "args": [ + "g", + "${input:componentType}", + "${input:componentName}" + ], + } + ], + "inputs": [ + { + "type": "pickString", + "id": "componentType", + "description": "What type of component do you want to create?", + "options": ["component", "directive", "pipe", "service", "class", "guard", "interface", "enum", "enum"], + "default": "component" + }, + { + "type": "promptString", + "id": "componentName", + "description": "Name your component.", + "default": "my-new-component" + } + ] +} +``` + +Running the example: + +![Inputs Example](images/tasks/run-input-example.gif) + +The following example shows how to use a user input variable of type `command` in a debug configuration that lets the user pick a test case from a list of all test cases found in a specific folder. It is assumed that some extension provides an `extension.mochaSupport.testPicker` command that locates all test cases in a configurable location and shows a picker UI to pick one of them. + +```json +{ + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Run specific test", + "program": "${workspaceFolder}/${input:pickTest}" + } + ], + "inputs": [ + { + "id": "pickTest", + "type": "command", + "command": "extension.mochaSupport.testPicker", + "args": { + "testFolder": "${workspaceFolder}/tests", + } + } + ] +} +``` + +## Common questions + +### Is variable substitution supported in User and Workspace settings? + +No, the predefined variables are not supported in strings in `settings.json` files. Some [settings](/docs/getstarted/settings.md) like `window.title` have their own variables: + +```json + "window.title": "${dirty}${activeEditorShort}${separator}${rootName}${separator}${appName}" +``` + +Refer to the comments in the Settings editor (`kb(workbench.action.openSettings)`) to learn about setting specific variables. + +### Why isn't ${workspaceRoot} documented? + +The variable `${workspaceRoot}` was deprecated in favor of `${workspaceFolder}` to better align with [Multi-root Workspace](/docs/editor/multi-root-workspaces.md) support. + +### How can I know a variable's actual value? + +One easy way to check a variable's runtime value is to create a VS Code [task](/docs/editor/tasks.md) to output the variable value to the console. For example, to see the resolved value for `${workspaceFolder}`, you can create and run (**Terminal** > **Run Task**) the following simple 'echo' task in `tasks.json`: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "echo", + "type": "shell", + "command": "echo ${workspaceFolder}" + } + ] +} diff --git a/docs/editor/versioncontrol.md b/docs/editor/versioncontrol.md new file mode 100644 index 0000000000000000000000000000000000000000..c138fa85e1f5ae6b8513e58df34cdff67077c011 --- /dev/null +++ b/docs/editor/versioncontrol.md @@ -0,0 +1,243 @@ +--- +Order: 8 +Area: editor +TOCTitle: Version Control +ContentId: 7E22CCC0-2AB8-4729-A4C9-BE2B16853820 +PageTitle: Version Control in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code source code support with integrated Git support. +--- +# Using Version Control in VS Code + +Visual Studio Code has integrated source control and includes [Git](https://git-scm.com/) support in-the-box. Many other source control providers are available through [extensions](/docs/editor/extension-gallery.md) on the VS Code Marketplace. + +
+ +> **Tip:** Click on an extension tile to read the description and reviews in the Marketplace. + +## SCM Providers + +VS Code has support for handling multiple Source Control providers simultaneously. For example, you can open multiple Git repositories alongside your TFS local workspace and seamlessly work across your projects. The **SOURCE CONTROL PROVIDERS** list of the **Source Control** view (`kb(workbench.view.scm)`) shows the detected providers and repositories and you can scope the display of your changes by selecting a specific provider. + +![source control providers](images/versioncontrol/scm.png) + +### SCM Provider extensions + +If you would like to install an additional SCM provider, you can search on the **scm providers** extension category in the Extensions view (`kb(workbench.view.extensions)`). Start typing '@ca' and you will see suggestions for extension categories like debuggers and linters. Select `@category:"scm providers"` to see available SCM providers. + +![scm provider category](images/versioncontrol/scm-provider-category.png) + +## Git support + +VS Code ships with a Git source control manager (SCM) extension. Most of the source control UI and work flows are common across other SCM extensions so reading about the Git support will help you understand how to use another provider. + +>**Note:** If you are new to Git, the [git-scm](https://git-scm.com/documentation) website is a good place to start with a popular online [book](https://git-scm.com/book), Getting Started [videos](https://git-scm.com/video/what-is-git) and [cheat sheets](https://services.github.com/on-demand/downloads/github-git-cheat-sheet.pdf). The VS Code documentation assumes you are already familiar with Git. + +![Git overview](images/versioncontrol/overview.png) + +>**Note:** VS Code will leverage your machine's Git installation, so you need to [install Git](https://git-scm.com/download) first before you get these features. Make sure you install at least version `2.0.0`. + +>**Tip:** VS Code will work with any Git repository. If you don't already have a private hosted Git provider, [Azure DevOps Services](https://azure.microsoft.com/services/devops) is a great free option. [Click here to sign-up](https://go.microsoft.com/fwlink/?LinkID=307137&campaign=o~msft~code~vc). + +The Source Control icon on the left will always indicate an **overview of how many changes** you currently have in your repository. Clicking it will show you the details of your current repository changes: **CHANGES**, **STAGED CHANGES** and **MERGE CHANGES**. + +Clicking each item will show you in detail **the textual changes within each file**. Note that for unstaged changes, the editor on the right still lets you edit the file: feel free to use it! + +You can also find indicators of the **status of your repository** in the bottom left corner of VS Code: the **current branch**, **dirty indicators** and the number of **incoming and outgoing commits** of the current branch. You can **checkout** any branch in your repository by clicking that status indicator and selecting the Git reference from the list. + +> **Tip:** You can open VS Code in a sub-directory of a Git repository. VS Code's Git services will still work as usual, showing all changes within the repository, but file changes outside of the scoped directory are shaded with a tool tip indicating they are located outside the current workspace. + +## Commit + +**Staging** (git add) and **unstaging** (git reset) can be done via contextual actions in the files or by drag-and-drop. + +![stage changes button](images/versioncontrol/stage-changes.png) + +You can type a commit message above the changes and press `kbstyle(Ctrl+Enter)` (macOS: `kbstyle(⌘+Enter)`) to commit them. If there are any staged changes, only those will be committed, otherwise all changes will be committed. + +We've found this to be a great workflow. For example, in the earlier screenshot, only the staged changes to `gulpfile.js` will be included in the commit. A consecutive commit action could commit later changes to `gulpfile.js`, the deletion of `yarn.lock`, and changes to `tests.js` in a separate commit. + +More specific **Commit** actions can be found in the **More Actions** `...` menu on the top of the Git view. + +![more actions button](images/versioncontrol/scm-more-actions.png) + +## Cloning a repository + +You can clone a Git repository with the **Git: Clone** command in the **Command Palette** (`kb(workbench.action.showCommands)`). You will be asked for the URL of the remote repository (for example on [GitHub](https://github.com/)) and the parent directory under which to put the local repository. + +For a GitHub repository, you would find the URL from the GitHub **Clone or download** dialog. + +![clone repository dialog](images/versioncontrol/GitHub-clone-dialog.png) + +You would then paste that URL into the **Git: Clone** prompt. + +![set repository URL](images/versioncontrol/set-repo-URL.png) + +## Branches and Tags + +You can create and checkout branches directly within VS code through the **Git: Create Branch** and **Git: Checkout to** commands in the **Command Palette** (`kb(workbench.action.showCommands)`). + +If you run **Git: Checkout to**, you will see a drop-down list containing all of the branches or tags in the current repository. + +![Git checkout](images/versioncontrol/gitbranches.png) + +The **Git: Create Branch** command lets you quickly create a new branch. Just provide the name of your new branch and VS Code will create the branch and switch to it. + +## Remotes + +Given that your repository is connected to some remote and that your checked out branch has an [upstream link](https://git-scm.com/book/ch3-5.html) to a branch in that remote, VS Code offers you useful actions to **push**, **pull** and **sync** that branch (the latter will run a **pull** command followed by a **push** command). You can find these actions in the **More Actions** `...` menu. + +VS Code is able to periodically fetch changes from your remotes. This enables VS Code to show how many changes your local repository is ahead or behind the remote. Starting with VS Code 1.19, this feature is disabled by default and you use the `git.autofetch` [setting](/docs/getstarted/settings.md) to enable it. + +>**Tip:** You should [set up a credential helper](https://help.github.com/articles/caching-your-github-password-in-git/) to avoid getting asked for credentials every time VS Code talks to your Git remotes. If you don't do this, you may want to consider disabling automatic fetching via the `git.autofetch` [setting](/docs/getstarted/settings.md) to reduce the number of prompts you get. + +## Git Status Bar actions + +There is a **Synchronize Changes** action in the Status Bar, next to the branch indicator, when the current checked out branch has an upstream branch configured. **Synchronize Changes** will pull remote changes down to your local repository and then push local commits to the upstream branch. + +![git status bar sync](images/versioncontrol/git-status-bar-sync.png) + +If there is no upstream branch configured and the Git repository has remotes set up, the **Publish** action is enabled. This will let you publish the current branch to a remote. + +![git status bar publish](images/versioncontrol/git-status-bar-publish.png) + +## Gutter indicators + +If you open a folder that is a Git repository and begin making changes, VS Code will add useful annotations to the gutter and to the overview ruler. + +* A red triangle indicates where lines have been deleted +* A green bar indicates new added lines +* A blue bar indicates modified lines + +![Gutter indicators](images/editingevolved/gutter.png) + +## Merge conflicts + +![Git merge](images/versioncontrol/merge-conflict.png) + +Merge conflicts are recognized by VS Code. Differences are highlighted and there are inline actions to accept either or both changes. Once the conflicts are resolved, stage the conflicting file so you can commit those changes. + +## Viewing diffs + +Our Git tooling supports viewing of diffs within VS Code. + +![A File Diff in VS Code](images/versioncontrol/diff.png) + +>**Tip:** You can diff any two files by first right clicking on a file in the Explorer or **OPEN EDITORS** list and selecting **Select for Compare** and then right-click on the second file to compare with and select **Compare with 'file_name_you_chose'**. Alternatively from the keyboard hit `kb(workbench.action.showCommands)` and select **File: Compare Active File With** and you will be presented with a list of recent files. + +### Diff editor review pane + +There is a review pane in the Diff editor which presents changes in a unified patch format. You can navigate between changes with **Go to Next Difference** (`kb(editor.action.diffReview.next)`) and **Go to Previous Difference** (`kb(editor.action.diffReview.prev)`). Lines can be navigated with arrow keys and pressing `kbstyle(Enter)` will jump back in the Diff editor and the selected line. + +![diff-review-pane](images/versioncontrol/diff-review-pane.png) + +**Note:** This experience is especially helpful for screen reader users. + +## Git output window + +You can always peek under the hood to see the Git commands we are using. This is helpful if something strange is happening or if you are just curious. :) + +To open the Git output window, run **View** > **Output** and select **Git** from the drop-down list. + +## Initialize a repository + +If your workspace isn't under Git source control, you can easily create a Git repository with the **Initialize Repository** command. When VS Code doesn't detect an existing Git repository, you will see a **There are no active source control providers.** message in the Source Control view and the **Initialize Repository** command will be available on the title bar. You can also run the **Git: Initialize Repository** command from the **Command Palette** (`kb(workbench.action.showCommands)`). + +![Git initialize repository](images/versioncontrol/git-initialize.png) + +Running **Initialize Repository** will create the necessary Git repository metadata files and show your workspace files as untracked changes ready to be staged. + +## VS Code as Git editor + +When you launch VS Code from the command line, you can pass the `--wait` argument to make the launch command wait until you have closed the new VS Code instance. This can be useful when you configure VS Code as your Git external editor so Git will wait until you close the launched VS Code instance. + +Here are the steps to do so: + +1. Make sure you can run `code --help` from the command line and you get help. + * if you do not see help, please follow these steps: + * macOS: Select **Shell Command: Install 'Code' command in path** from the **Command Palette**. + * Windows: Make sure you selected **Add to PATH** during the installation. + * Linux: Make sure you installed Code via our new .deb or .rpm packages. +2. From the command line, run `git config --global core.editor "code --wait"` + +Now you can run `git config --global -e` and use VS Code as editor for configuring Git. + +![git config in VS Code](images/versioncontrol/gitconfig.png) + +### VS Code as Git diff tool + +Add the following to your Git configurations to use VS Code as the diff tool: + +```bash +[diff] + tool = default-difftool +[difftool "default-difftool"] + cmd = code --wait --diff $LOCAL $REMOTE +``` + +This leverages the `--diff` option you can pass to VS Code to compare 2 files side by side. + +To summarize, here are some examples of where you can use VS Code as the editor: + +* `git rebase HEAD~3 -i` do interactive rebase using VS Code +* `git commit` use VS Code for the commit message +* `git add -p` followed by `kbstyle(e)` for interactive add +* `git difftool ^ ` use VS Code as the diff editor for changes + +## Working with pull requests + +Visual Studio Code also supports pull request workflows through [extensions](/docs/editor/extension-gallery.md) available on the VS Code Marketplace. Pull request extensions let you review, comment, and verify source code contributions directly within VS Code. + +
+ +> **Tip:** Click on an extension tile to read the description and reviews in the Marketplace. + +## Next steps + +* [Intro Video - Git Version Control](/docs/introvideos/versioncontrol.md) - An introductory video providing an overview of VS Code Git support. +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Debugging](/docs/editor/debugging.md) - This is where VS Code really shines +* [Tasks](/docs/editor/tasks.md) - Running tasks with Gulp, Grunt and Jake. Showing Errors and Warnings +* [Source Control API](/api/extension-guides/scm-provider.md) - If you want to integrate another Source Control provider into VS Code, see our Source Control API. + +## Common questions + +### I initialized my repo but the actions in the `...` menu are all grayed out + +To **push, pull, and sync** you need to have a Git origin set up. You can get the required URL from the repo host. Once you have that URL, you need to add it to the Git settings by running a couple of command line actions. For example: + +```bash +> git remote add origin https://github.com//.git +> git push -u origin master +``` + +### My team is using Team Foundation Version Control (TFVC) instead of Git. What should I do? + +Use the [Azure Repos](https://marketplace.visualstudio.com/items?itemName=ms-vsts.team) extension and this will light up TFVC support. + +### Why do the Pull, Push and Sync actions never finish? + +This usually means there is no credential management configured in Git and you're not getting credential prompts for some reason. + +You can always set up a [credential helper](https://help.github.com/articles/caching-your-github-password-in-git/) in order to pull and push from a remote server without having VS Code prompt for your credentials each time. + +### How can I sign into Git with my Azure DevOps organization which requires multi-factor authentication? + +There are now [Git credential helpers](https://devblogs.microsoft.com/devops/git-credential-manager-for-mac-and-linux) that assist with multi-factor authentication. You can download these from [Git Credential Manager for Mac and Linux](https://github.com/Microsoft/Git-Credential-Manager-for-Mac-and-Linux) and [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows). + +### I have GitHub Desktop installed on my computer but VS Code ignores it + +VS Code only supports the [official Git distribution](https://git-scm.com/) for its Git integration. + +### I keep getting Git authentication dialogs whenever VS Code is running + +VS Code automatically fetches changes from the server in order to present you with a summary of incoming changes. The Git authentication dialog is independent from VS Code itself and is a part of your current Git credential helper. + +One way to avoid these prompts is to set up a [credential helper](https://help.github.com/articles/caching-your-github-password-in-git/) which remembers your credentials. + +Another option is to disable the auto fetch feature by changing the following setting: `"git.autofetch": false`. + +### Can I use SSH Git authentication with VS Code? + +Yes, though VS Code works most easily with SSH keys without a passphrase. If you have a SSH key with a passphrase, you'll need to launch VS Code from a Git Bash prompt to inherit its SSH environment. diff --git a/docs/editor/whyvscode.md b/docs/editor/whyvscode.md new file mode 100644 index 0000000000000000000000000000000000000000..cd11a9b87b14ca3e2bd60100bd345e6d364c0eaf --- /dev/null +++ b/docs/editor/whyvscode.md @@ -0,0 +1,56 @@ +--- +Order: +Area: editor +TOCTitle: Why VS Code +ContentId: FF543B32-703C-4894-9A3B-2B5BFAF8B6B8 +PageTitle: Why Visual Studio Code? +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code provides developers with a new choice of tool that combines the simplicity of a code editor with the best tooling for their core edit-build-debug cycle. Visual Studio Code is available for macOS, Linux, and Windows. +--- +# Why did we build Visual Studio Code? + +Visual Studio Code combines the simplicity of a source code editor with powerful developer tooling, like IntelliSense code completion and debugging. + +First and foremost, it is an editor that gets out of your way. The delightfully frictionless edit-build-debug cycle means less time fiddling with your environment, and more time executing on your ideas. + +## Available for macOS, Linux, and Windows + +Visual Studio Code supports macOS, Linux, and Windows - so you can hit the ground running, no matter the platform. + +![Visual Studio Code runs on macOS, Linux and Windows](images/whyvscode/macwinlinux2.png) + +## Edit, build, and debug with ease + +At its heart, Visual Studio Code features a lightning fast source code editor, perfect for day-to-day use. With support for hundreds of languages, VS Code helps you be instantly productive with syntax highlighting, bracket-matching, auto-indentation, box-selection, snippets, and more. Intuitive keyboard shortcuts, easy customization and community-contributed keyboard shortcut mappings let you navigate your code with ease. + +For serious coding, you'll often benefit from tools with more code understanding than just blocks of text. Visual Studio Code includes built-in support for IntelliSense code completion, rich semantic code understanding and navigation, and code refactoring. + +And when the coding gets tough, the tough get debugging. Debugging is often the one feature that developers miss most in a leaner coding experience, so we made it happen. Visual Studio Code includes an interactive debugger, so you can step through source code, inspect variables, view call stacks, and execute commands in the console. + +VS Code also integrates with build and scripting tools to perform common tasks making everyday workflows faster. VS Code has support for Git so you can work with source control without leaving the editor including viewing pending changes diffs. + +## Make it your own + +Customize every feature to your liking and install any number of third-party extensions. While most scenarios work "out of the box" with no configuration, VS Code also grows with you, and we encourage you to optimize your experience to suit your unique needs. VS Code is an open source project so you can also contribute to the growing and vibrant community on GitHub. + +## Built with love for the Web + +VS Code includes enriched built-in support for Node.js development with JavaScript and TypeScript, powered by the same underlying technologies that drive Visual Studio. VS Code also includes great tooling for web technologies such as JSX/React, HTML, CSS, SCSS, Less, and JSON. + +## Robust and extensible architecture + +Architecturally, Visual Studio Code combines the best of web, native, and language-specific technologies. Using [Electron](https://github.com/electron/electron), VS Code combines web technologies such as JavaScript and Node.js with the speed and flexibility of native apps. VS Code uses a newer, faster version of the same industrial-strength HTML-based editor that has powered the “Monaco” cloud editor, Internet Explorer's F12 Tools, and other projects. Additionally, VS Code uses a tools service architecture that enables it to integrate with many of the same technologies that power Visual Studio, including Roslyn for .NET, TypeScript, the Visual Studio debugging engine, and more. + +Visual Studio Code includes a public extensibility model that lets developers build and use extensions, and richly customize their edit-build-debug experience. + +## Ready, set, code! + +If you prefer a code editor-centric development tool or are building cross-platform web and cloud applications, we invite you to try out Visual Studio Code and let us know what you think! + +## Next steps + +Read on to find out about: + +* [Visual Studio Code User Interface](/docs/getstarted/userinterface.md) - A quick orientation to VS Code. +* [Intro Videos](/docs/getstarted/introvideos.md) - Learn about the VS Code editor features. +* [Debugging](/docs/editor/debugging.md) - OK time for the really fun stuff - break, step, watch. diff --git a/docs/getstarted/images/introvideos/opengraph_insiders.png b/docs/getstarted/images/introvideos/opengraph_insiders.png new file mode 100644 index 0000000000000000000000000000000000000000..42b3b4886d81d05b96b0a1c6c6666c70f151f759 Binary files /dev/null and b/docs/getstarted/images/introvideos/opengraph_insiders.png differ diff --git a/docs/getstarted/images/keybinding/customization_keybindings.png b/docs/getstarted/images/keybinding/customization_keybindings.png new file mode 100644 index 0000000000000000000000000000000000000000..58bcdfb10022079935dea01997e3bbe62ffd8355 Binary files /dev/null and b/docs/getstarted/images/keybinding/customization_keybindings.png differ diff --git a/docs/getstarted/images/keybinding/key-binding-widget.png b/docs/getstarted/images/keybinding/key-binding-widget.png new file mode 100644 index 0000000000000000000000000000000000000000..783da818a92fc26ccd7e25b44d893ed209134d43 Binary files /dev/null and b/docs/getstarted/images/keybinding/key-binding-widget.png differ diff --git a/docs/getstarted/images/keybinding/keybindings-json.png b/docs/getstarted/images/keybinding/keybindings-json.png new file mode 100644 index 0000000000000000000000000000000000000000..570f3d5ae5c513020916b71c45a72862539c45fe Binary files /dev/null and b/docs/getstarted/images/keybinding/keybindings-json.png differ diff --git a/docs/getstarted/images/keybinding/keyboard-shortcuts.gif b/docs/getstarted/images/keybinding/keyboard-shortcuts.gif new file mode 100644 index 0000000000000000000000000000000000000000..b5f391a9a95223b81f0925d20d245c8b35179fa6 --- /dev/null +++ b/docs/getstarted/images/keybinding/keyboard-shortcuts.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:571c00c05269ca066de994d27c7618b22c0872bb42b2eb4d2a743a7c91ceea36 +size 1111409 diff --git a/docs/getstarted/images/keybinding/outline.png b/docs/getstarted/images/keybinding/outline.png new file mode 100644 index 0000000000000000000000000000000000000000..c22e9ff13784f70cbc91e1271be6bf9ced223d61 Binary files /dev/null and b/docs/getstarted/images/keybinding/outline.png differ diff --git a/docs/getstarted/images/keybinding/render-key-binding.png b/docs/getstarted/images/keybinding/render-key-binding.png new file mode 100644 index 0000000000000000000000000000000000000000..0b32b48f98f6cecd0b62b5010265b2298a0011b1 Binary files /dev/null and b/docs/getstarted/images/keybinding/render-key-binding.png differ diff --git a/docs/getstarted/images/keybinding/show-conflicts-menu.png b/docs/getstarted/images/keybinding/show-conflicts-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..6554f6ea4394ac71f811a8de29f95de7f5c09beb Binary files /dev/null and b/docs/getstarted/images/keybinding/show-conflicts-menu.png differ diff --git a/docs/getstarted/images/keybinding/show-conflicts-result.png b/docs/getstarted/images/keybinding/show-conflicts-result.png new file mode 100644 index 0000000000000000000000000000000000000000..f6bccdaf9eb59b702dfecad387de52db1822b2d8 Binary files /dev/null and b/docs/getstarted/images/keybinding/show-conflicts-result.png differ diff --git a/docs/getstarted/images/locales/German-language-pack.png b/docs/getstarted/images/locales/German-language-pack.png new file mode 100644 index 0000000000000000000000000000000000000000..e4c6c9a5773738401d7cb5558dc7b9c513d24cc8 Binary files /dev/null and b/docs/getstarted/images/locales/German-language-pack.png differ diff --git a/docs/getstarted/images/locales/configure-language-command.png b/docs/getstarted/images/locales/configure-language-command.png new file mode 100644 index 0000000000000000000000000000000000000000..2a5ae74867c21c7d3f1964f8e28b27335b30d621 Binary files /dev/null and b/docs/getstarted/images/locales/configure-language-command.png differ diff --git a/docs/getstarted/images/locales/lang-pack-recommendation.png b/docs/getstarted/images/locales/lang-pack-recommendation.png new file mode 100644 index 0000000000000000000000000000000000000000..0b3bd418a0e5a64bfbf469fefb32f7e86c3618e9 Binary files /dev/null and b/docs/getstarted/images/locales/lang-pack-recommendation.png differ diff --git a/docs/getstarted/images/locales/locale-intellisense.png b/docs/getstarted/images/locales/locale-intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..c309c01f7c6ba6fe23f06bdf3387f2d54edc94f7 Binary files /dev/null and b/docs/getstarted/images/locales/locale-intellisense.png differ diff --git a/docs/getstarted/images/settings/hero.png b/docs/getstarted/images/settings/hero.png new file mode 100644 index 0000000000000000000000000000000000000000..6c7201225975fec6bae533124e251a1c32f2553f Binary files /dev/null and b/docs/getstarted/images/settings/hero.png differ diff --git a/docs/getstarted/images/settings/lang-based-settings.png b/docs/getstarted/images/settings/lang-based-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..0417e256393fbbf5da26b3569c51902db4091531 --- /dev/null +++ b/docs/getstarted/images/settings/lang-based-settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4f811e89fd199f8a9be2de32398215197c8ab7cd9692ee02d3b2479d80414e6c +size 414087 diff --git a/docs/getstarted/images/settings/lang-selection.png b/docs/getstarted/images/settings/lang-selection.png new file mode 100644 index 0000000000000000000000000000000000000000..3eef7fc55b0aa7cfc498bd2991a4a4d421de44a8 Binary files /dev/null and b/docs/getstarted/images/settings/lang-selection.png differ diff --git a/docs/getstarted/images/settings/pref-config-lang-settings.png b/docs/getstarted/images/settings/pref-config-lang-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..6f724263cd273c717c989a8e9d4e19af0de77e6b Binary files /dev/null and b/docs/getstarted/images/settings/pref-config-lang-settings.png differ diff --git a/docs/getstarted/images/settings/settings-edit.png b/docs/getstarted/images/settings/settings-edit.png new file mode 100644 index 0000000000000000000000000000000000000000..c0236349bd473ebb60ee0ed7d87c5b4c3d85d790 Binary files /dev/null and b/docs/getstarted/images/settings/settings-edit.png differ diff --git a/docs/getstarted/images/settings/settings-groups.png b/docs/getstarted/images/settings/settings-groups.png new file mode 100644 index 0000000000000000000000000000000000000000..e088c0cc513c39f7d6b15dae167e1b5cbf18feeb Binary files /dev/null and b/docs/getstarted/images/settings/settings-groups.png differ diff --git a/docs/getstarted/images/settings/settings-search.png b/docs/getstarted/images/settings/settings-search.png new file mode 100644 index 0000000000000000000000000000000000000000..888d4d3cba49c0a26206e60a1c3f8585d95f0af1 Binary files /dev/null and b/docs/getstarted/images/settings/settings-search.png differ diff --git a/docs/getstarted/images/settings/settings.png b/docs/getstarted/images/settings/settings.png new file mode 100644 index 0000000000000000000000000000000000000000..277057dfb21a9243c5d8e742cde381f227ab35d6 Binary files /dev/null and b/docs/getstarted/images/settings/settings.png differ diff --git a/docs/getstarted/images/themes/built-in-themes.png b/docs/getstarted/images/themes/built-in-themes.png new file mode 100644 index 0000000000000000000000000000000000000000..ecce08964d2f538aba2ea3511a065f8f9c4ff82c --- /dev/null +++ b/docs/getstarted/images/themes/built-in-themes.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9f97f5e0fa16af967d50c6b45f4755d8652d5a62dc462a5bd4408076b6deca29 +size 113349 diff --git a/docs/getstarted/images/themes/colorthemes.png b/docs/getstarted/images/themes/colorthemes.png new file mode 100644 index 0000000000000000000000000000000000000000..38fcca0f9a90a9f6964c63e262f0b6e335454a52 Binary files /dev/null and b/docs/getstarted/images/themes/colorthemes.png differ diff --git a/docs/getstarted/images/themes/disable-theme.png b/docs/getstarted/images/themes/disable-theme.png new file mode 100644 index 0000000000000000000000000000000000000000..da65eda78229fd50fa2e9cb6e7658aa9bc4d2e04 Binary files /dev/null and b/docs/getstarted/images/themes/disable-theme.png differ diff --git a/docs/getstarted/images/themes/file-icon-theme-dropdown.png b/docs/getstarted/images/themes/file-icon-theme-dropdown.png new file mode 100644 index 0000000000000000000000000000000000000000..7fabc05b5d7aa1e6d7277b7bf789067e367da0da Binary files /dev/null and b/docs/getstarted/images/themes/file-icon-theme-dropdown.png differ diff --git a/docs/getstarted/images/themes/inspect-tm-scopes.png b/docs/getstarted/images/themes/inspect-tm-scopes.png new file mode 100644 index 0000000000000000000000000000000000000000..a09fb2d8432414d050e658281d1aaa98921ef0bc Binary files /dev/null and b/docs/getstarted/images/themes/inspect-tm-scopes.png differ diff --git a/docs/getstarted/images/themes/theme-activitybar.gif b/docs/getstarted/images/themes/theme-activitybar.gif new file mode 100644 index 0000000000000000000000000000000000000000..9d8d09aec8723eb163fe1fa9fb31f7def3643d1e --- /dev/null +++ b/docs/getstarted/images/themes/theme-activitybar.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6aac6a5f681ad109f4b7062c8e643f899a789597a47015ce6b36db4d6ec3091e +size 2217617 diff --git a/docs/getstarted/images/themes/themes_hero.gif b/docs/getstarted/images/themes/themes_hero.gif new file mode 100644 index 0000000000000000000000000000000000000000..7a45a7cf94ffeab30abc3a5bd6d05dbc4fb5b7b8 Binary files /dev/null and b/docs/getstarted/images/themes/themes_hero.gif differ diff --git a/docs/getstarted/images/themes/token_color_customization.png b/docs/getstarted/images/themes/token_color_customization.png new file mode 100644 index 0000000000000000000000000000000000000000..ae2a89847a94aea9969babe75ec4d2d160f4d91a Binary files /dev/null and b/docs/getstarted/images/themes/token_color_customization.png differ diff --git a/docs/getstarted/images/themes/token_color_customization_advanced.png b/docs/getstarted/images/themes/token_color_customization_advanced.png new file mode 100644 index 0000000000000000000000000000000000000000..d441c80bd58f9c89b319aa9ed973378be82c4365 Binary files /dev/null and b/docs/getstarted/images/themes/token_color_customization_advanced.png differ diff --git a/docs/getstarted/images/themes/yocodetheme.png b/docs/getstarted/images/themes/yocodetheme.png new file mode 100644 index 0000000000000000000000000000000000000000..e42517ccdd1813b5cff4abb626a2d6b4d0930f6b Binary files /dev/null and b/docs/getstarted/images/themes/yocodetheme.png differ diff --git a/docs/getstarted/images/tips-and-tricks/Errors_Warnings.gif b/docs/getstarted/images/tips-and-tricks/Errors_Warnings.gif new file mode 100644 index 0000000000000000000000000000000000000000..f22baf4dcf8cff61d5b6f62ed26c91730ccf08b0 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/Errors_Warnings.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7c9633f3cee38450b7f60dee00e852d304fb8981f1fb4ba5e1188768f3645eb8 +size 193706 diff --git a/docs/getstarted/images/tips-and-tricks/InstallExtensions.gif b/docs/getstarted/images/tips-and-tricks/InstallExtensions.gif new file mode 100644 index 0000000000000000000000000000000000000000..ebd3e3727251c1f69d8eaabe7e34f5f6f4ba7c73 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/InstallExtensions.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6680a5d666cb4eb7cfa4eb2cd2771038e39b73358efbd3e30b507f09d81cd148 +size 1928493 diff --git a/docs/getstarted/images/tips-and-tricks/KeyboardReferenceSheet.png b/docs/getstarted/images/tips-and-tricks/KeyboardReferenceSheet.png new file mode 100644 index 0000000000000000000000000000000000000000..9b823a9e156f8fd7b8916e01e18aaeb98c700a03 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/KeyboardReferenceSheet.png differ diff --git a/docs/getstarted/images/tips-and-tricks/KeyboardShortcuts.gif b/docs/getstarted/images/tips-and-tricks/KeyboardShortcuts.gif new file mode 100644 index 0000000000000000000000000000000000000000..06f0c950dfd598a34ec57bb6f729de786844009e --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/KeyboardShortcuts.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:427a271a99a460feef45e1cf4f07985559197c3ea02dbec91e3b45a4c89dff9e +size 224072 diff --git a/docs/getstarted/images/tips-and-tricks/OpenCommandPalatte.gif b/docs/getstarted/images/tips-and-tricks/OpenCommandPalatte.gif new file mode 100644 index 0000000000000000000000000000000000000000..214e2a3c39629a6f0767473c79df56c1835e93ad --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/OpenCommandPalatte.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f21185fc83663486784c3f48bcb1960e35ac6ef71727a8ccaa61497cd7990733 +size 125006 diff --git a/docs/getstarted/images/tips-and-tricks/PreviewFileIconThemes.gif b/docs/getstarted/images/tips-and-tricks/PreviewFileIconThemes.gif new file mode 100644 index 0000000000000000000000000000000000000000..b10a3719b05216f2b82216263d18c5c9fe2f83ec --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/PreviewFileIconThemes.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1b1d6d530eaf7decc946b1cb16afb853bcb7012d5857299413afd0e33c9f6abb +size 543177 diff --git a/docs/getstarted/images/tips-and-tricks/PreviewThemes.gif b/docs/getstarted/images/tips-and-tricks/PreviewThemes.gif new file mode 100644 index 0000000000000000000000000000000000000000..322923f2177e81ba94135923101a779cd9789946 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/PreviewThemes.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:208190c558f88ebb87503288549630ecea95f8fa14590615892d3fd0ea66582d +size 743144 diff --git a/docs/getstarted/images/tips-and-tricks/QuickOpen.gif b/docs/getstarted/images/tips-and-tricks/QuickOpen.gif new file mode 100644 index 0000000000000000000000000000000000000000..534391ab56b9091bbcc85014eb6488c487c89be3 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/QuickOpen.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2917d4c40141628d0a5ebb595b046aa318924164115b7839d7dbc520b1961a9d +size 512652 diff --git a/docs/getstarted/images/tips-and-tricks/add_cursor_current_selection.gif b/docs/getstarted/images/tips-and-tricks/add_cursor_current_selection.gif new file mode 100644 index 0000000000000000000000000000000000000000..a1dc4405a51371144ae5ca9bed08ea7934235404 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/add_cursor_current_selection.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:61857029bf0759bb7406ad34c250dee9b81a6c4fbc4d50b471eee026e80c093f +size 250444 diff --git a/docs/getstarted/images/tips-and-tricks/add_cursor_current_selection_one_by_one.gif b/docs/getstarted/images/tips-and-tricks/add_cursor_current_selection_one_by_one.gif new file mode 100644 index 0000000000000000000000000000000000000000..a8645c25b8edc1c1d56587ee0b4aa75669190788 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/add_cursor_current_selection_one_by_one.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:049d725b016b8781e62f4b7bf3c6af741636766fc659ab36d1bb83df1040bdcd +size 399593 diff --git a/docs/getstarted/images/tips-and-tricks/change_syntax.gif b/docs/getstarted/images/tips-and-tricks/change_syntax.gif new file mode 100644 index 0000000000000000000000000000000000000000..921fe6a6b60e2578f9254e20bff80cbe7cc0e687 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/change_syntax.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b192396fac68da718b4cf01657b0721807b11d3f1bb809e24843c2005a985531 +size 395219 diff --git a/docs/getstarted/images/tips-and-tricks/code_folding.gif b/docs/getstarted/images/tips-and-tricks/code_folding.gif new file mode 100644 index 0000000000000000000000000000000000000000..be84835e14f4bdb11760c264a81810fcc738b55f --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/code_folding.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cc5da3df93d23b766c48fb23b61c832f11b3450dade1e8da1643451a9ce8f49e +size 503973 diff --git a/docs/getstarted/images/tips-and-tricks/code_formatting.gif b/docs/getstarted/images/tips-and-tricks/code_formatting.gif new file mode 100644 index 0000000000000000000000000000000000000000..872f1d63578d345b5897ff264942df4eabb07df3 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/code_formatting.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3bb2a9a46728afce46ec0ef8a2af9223fffbfb84b121cbdf46d73819dccc78e4 +size 238706 diff --git a/docs/getstarted/images/tips-and-tricks/column-select.gif b/docs/getstarted/images/tips-and-tricks/column-select.gif new file mode 100644 index 0000000000000000000000000000000000000000..f034bcb4a3c88e0c9a45595bd098c7551bb85afa --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/column-select.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:909c511fdb8439fab67aea9dbfb2cdc54499aaa1d586278d04fa43672511640b +size 128321 diff --git a/docs/getstarted/images/tips-and-tricks/command_p.png b/docs/getstarted/images/tips-and-tricks/command_p.png new file mode 100644 index 0000000000000000000000000000000000000000..3f18b1a4d2dc84126b6b246485b90504ca2f6103 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/command_p.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bbf158754f7df90489f1d65f2ac3e4fb72f115933253ba2594304b97103ac86a +size 160163 diff --git a/docs/getstarted/images/tips-and-tricks/configure_debug.gif b/docs/getstarted/images/tips-and-tricks/configure_debug.gif new file mode 100644 index 0000000000000000000000000000000000000000..2f64d9ba0fbd240630f0ae4901a42e5d3c8cb722 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/configure_debug.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8f23d42940bdc52779bdf6b39ba427c4806d6f2ae1c0b3dc4812dbcf17d9940e +size 164820 diff --git a/docs/getstarted/images/tips-and-tricks/copy_line_down.gif b/docs/getstarted/images/tips-and-tricks/copy_line_down.gif new file mode 100644 index 0000000000000000000000000000000000000000..2e660bbb33735e535a87fa172b65f5da16214446 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/copy_line_down.gif differ diff --git a/docs/getstarted/images/tips-and-tricks/create_open_file.gif b/docs/getstarted/images/tips-and-tricks/create_open_file.gif new file mode 100644 index 0000000000000000000000000000000000000000..91386a0f2cfc50e88184471b4a68702c3eba18f8 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/create_open_file.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:21358844c238914b5291df37f595aaf29514eb70ce032954307bbfccfec45f63 +size 206845 diff --git a/docs/getstarted/images/tips-and-tricks/debug_data_inspection.gif b/docs/getstarted/images/tips-and-tricks/debug_data_inspection.gif new file mode 100644 index 0000000000000000000000000000000000000000..aa147f065b5a33a380c07aa540222f9f70a63a15 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/debug_data_inspection.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1e47c32c33e49ff851168dbf89dacf75e92e6a811d043a99eb38d0522c679442 +size 1216804 diff --git a/docs/getstarted/images/tips-and-tricks/diff_review_pane.png b/docs/getstarted/images/tips-and-tricks/diff_review_pane.png new file mode 100644 index 0000000000000000000000000000000000000000..d5a3fb9b19d34cb4731154429c41ce0a9647ca19 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/diff_review_pane.png differ diff --git a/docs/getstarted/images/tips-and-tricks/dirty-write.png b/docs/getstarted/images/tips-and-tricks/dirty-write.png new file mode 100644 index 0000000000000000000000000000000000000000..9a20caa48614bf07dc98ed257f3416c738f58c50 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/dirty-write.png differ diff --git a/docs/getstarted/images/tips-and-tricks/editingevolved_gutter.png b/docs/getstarted/images/tips-and-tricks/editingevolved_gutter.png new file mode 100644 index 0000000000000000000000000000000000000000..c2ad59bb0659b17f3213688802c88da47e790106 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/editingevolved_gutter.png differ diff --git a/docs/getstarted/images/tips-and-tricks/emmet_syntax.gif b/docs/getstarted/images/tips-and-tricks/emmet_syntax.gif new file mode 100644 index 0000000000000000000000000000000000000000..3614e89d00a01e992b78a121269c7cb866a568d5 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/emmet_syntax.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c376044492d8561584e1fb94685f3017ae93b3770958afc87dd599123073c3f7 +size 177032 diff --git a/docs/getstarted/images/tips-and-tricks/find_all_references.gif b/docs/getstarted/images/tips-and-tricks/find_all_references.gif new file mode 100644 index 0000000000000000000000000000000000000000..a0772c29eeef6f01260c6073946a2e1071829709 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/find_all_references.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:040869b8d086df87e0eb610a591838e6580106d71dfab598cc6a56d106315743 +size 569182 diff --git a/docs/getstarted/images/tips-and-tricks/find_by_symbol.gif b/docs/getstarted/images/tips-and-tricks/find_by_symbol.gif new file mode 100644 index 0000000000000000000000000000000000000000..956878376c33db4d12d00ee3e3a3908609859aac --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/find_by_symbol.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:65e2614631408ea331052d2b91947c8d3629f28b96649606c8f2e606eed8d4c0 +size 737754 diff --git a/docs/getstarted/images/tips-and-tricks/font-ligatures-annotated.png b/docs/getstarted/images/tips-and-tricks/font-ligatures-annotated.png new file mode 100644 index 0000000000000000000000000000000000000000..6e731a81d7c3f45d4127669bd5a2330049e040b6 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/font-ligatures-annotated.png differ diff --git a/docs/getstarted/images/tips-and-tricks/font-ligatures.png b/docs/getstarted/images/tips-and-tricks/font-ligatures.png new file mode 100644 index 0000000000000000000000000000000000000000..211dce0b26f7717832934be51695952f6913f405 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/font-ligatures.png differ diff --git a/docs/getstarted/images/tips-and-tricks/git_inline.png b/docs/getstarted/images/tips-and-tricks/git_inline.png new file mode 100644 index 0000000000000000000000000000000000000000..1759f6ecce67cd5c91e97f198269e9e2f8458bc7 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/git_inline.png differ diff --git a/docs/getstarted/images/tips-and-tricks/git_side_by_side.png b/docs/getstarted/images/tips-and-tricks/git_side_by_side.png new file mode 100644 index 0000000000000000000000000000000000000000..9cea03d4003d7624e527ac44502139c4e5e504f3 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/git_side_by_side.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f2a8b59cf09e3b2da4e0a99c61582a363ec0f508b37ddf00afab79da2fbb460d +size 124297 diff --git a/docs/getstarted/images/tips-and-tricks/git_stage_all.gif b/docs/getstarted/images/tips-and-tricks/git_stage_all.gif new file mode 100644 index 0000000000000000000000000000000000000000..14fddec8aa145f934a7b8134cb410c4a575eea91 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/git_stage_all.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:345350779ced2b6659df3a3be7c197881dd55717ec0583c0f386441d52806496 +size 110828 diff --git a/docs/getstarted/images/tips-and-tricks/go_to_symbol_in_workspace.png b/docs/getstarted/images/tips-and-tricks/go_to_symbol_in_workspace.png new file mode 100644 index 0000000000000000000000000000000000000000..65fa770ab4dfc16ae242cddd9b2f41a482c32352 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/go_to_symbol_in_workspace.png differ diff --git a/docs/getstarted/images/tips-and-tricks/goto_definition.gif b/docs/getstarted/images/tips-and-tricks/goto_definition.gif new file mode 100644 index 0000000000000000000000000000000000000000..7d6b3455c38e602a3fc702815b62d2229c00a6e5 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/goto_definition.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:58036194bfdaa60de24ed3c4e10186c5b50827987996690002c922fca9b7d2c8 +size 1176326 diff --git a/docs/getstarted/images/tips-and-tricks/group_symbols_by_kind.png b/docs/getstarted/images/tips-and-tricks/group_symbols_by_kind.png new file mode 100644 index 0000000000000000000000000000000000000000..e06deb97ca99a431a73c161ccae5bf4496cd29ff Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/group_symbols_by_kind.png differ diff --git a/docs/getstarted/images/tips-and-tricks/integrated_terminal.png b/docs/getstarted/images/tips-and-tricks/integrated_terminal.png new file mode 100644 index 0000000000000000000000000000000000000000..351350b60f52db9a1cae8662f3568f4abac53365 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/integrated_terminal.png differ diff --git a/docs/getstarted/images/tips-and-tricks/intellisense.gif b/docs/getstarted/images/tips-and-tricks/intellisense.gif new file mode 100644 index 0000000000000000000000000000000000000000..99252659a44637fd08f1a295da35b0b2c3ac7fce --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/intellisense.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:573444feacd52aa34492644e9a7a1153d2b889e07af75c089309ebbb7d11aaf3 +size 560224 diff --git a/docs/getstarted/images/tips-and-tricks/interactive_playground.png b/docs/getstarted/images/tips-and-tricks/interactive_playground.png new file mode 100644 index 0000000000000000000000000000000000000000..d723f66d1aebe7151f04aa68d7cf0ae5510ab77b Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/interactive_playground.png differ diff --git a/docs/getstarted/images/tips-and-tricks/keyboard-references.png b/docs/getstarted/images/tips-and-tricks/keyboard-references.png new file mode 100644 index 0000000000000000000000000000000000000000..5ec640d44f9857960ef9e134a04281acc390d31d Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/keyboard-references.png differ diff --git a/docs/getstarted/images/tips-and-tricks/keyboard-shortcuts.png b/docs/getstarted/images/tips-and-tricks/keyboard-shortcuts.png new file mode 100644 index 0000000000000000000000000000000000000000..b53f86b90b13425f58a85db3d30864aa5a5271e8 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/keyboard-shortcuts.png differ diff --git a/docs/getstarted/images/tips-and-tricks/lang-based-settings.png b/docs/getstarted/images/tips-and-tricks/lang-based-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..91c4df229c9e882a9909e754c56f1a47f4d7d2a1 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/lang-based-settings.png differ diff --git a/docs/getstarted/images/tips-and-tricks/markdown-preview-side-by-side.png b/docs/getstarted/images/tips-and-tricks/markdown-preview-side-by-side.png new file mode 100644 index 0000000000000000000000000000000000000000..e77ca4991f8c91ea8fece8eb7750ca5cf522f7c3 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/markdown-preview-side-by-side.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7996869e4f35b39b190c58f9a120b1cc1ffead6ff046320830af567d753b5832 +size 195445 diff --git a/docs/getstarted/images/tips-and-tricks/markdown-preview.png b/docs/getstarted/images/tips-and-tricks/markdown-preview.png new file mode 100644 index 0000000000000000000000000000000000000000..49a485dbb02b986e18437d7910ed07bb40ff230d Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/markdown-preview.png differ diff --git a/docs/getstarted/images/tips-and-tricks/move_line.gif b/docs/getstarted/images/tips-and-tricks/move_line.gif new file mode 100644 index 0000000000000000000000000000000000000000..965d58a4f69a1bab5341d00ed88420a42f1c3430 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/move_line.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9f5162a9a02417a6eb6eed58342d5df9290ab080f1354d33b7d43f35c8124dff +size 506458 diff --git a/docs/getstarted/images/tips-and-tricks/mp_copy_paste.png b/docs/getstarted/images/tips-and-tricks/mp_copy_paste.png new file mode 100644 index 0000000000000000000000000000000000000000..3d921c5a7f6caa1df63e8ab1f13bdbf036805805 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/mp_copy_paste.png differ diff --git a/docs/getstarted/images/tips-and-tricks/multicursor.gif b/docs/getstarted/images/tips-and-tricks/multicursor.gif new file mode 100644 index 0000000000000000000000000000000000000000..680e3dd7027b4be24c912e3c01fec2fdd6055fd6 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/multicursor.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3dc142ad24bbf6996a1e99cc257a362a2dc94b8afcb14d129668020aeb74b6d6 +size 183900 diff --git a/docs/getstarted/images/tips-and-tricks/navigate_editors.gif b/docs/getstarted/images/tips-and-tricks/navigate_editors.gif new file mode 100644 index 0000000000000000000000000000000000000000..84dfbdb5369ee44142812b78d1d0bdc69e3915a8 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/navigate_editors.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6fb21806d95da1a6c6c831b6ee10ca0bc469f99294c742f689a3fdc48b7e3302 +size 264734 diff --git a/docs/getstarted/images/tips-and-tricks/navigate_history.gif b/docs/getstarted/images/tips-and-tricks/navigate_history.gif new file mode 100644 index 0000000000000000000000000000000000000000..0c2f247df55b96b349a5388297909b867b56d8fe --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/navigate_history.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8de45df2495272bf3b3ef6983dcc176f9f743a65c5864411f9bf7f3b90dc4649 +size 695380 diff --git a/docs/getstarted/images/tips-and-tricks/navigate_to_line.gif b/docs/getstarted/images/tips-and-tricks/navigate_to_line.gif new file mode 100644 index 0000000000000000000000000000000000000000..2a84ec4bfec23be3faaf758675ce89fce4580217 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/navigate_to_line.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f3430f89ad36931f93ea4f5c5d3985d33c2e0a75121f624492f150324f170593 +size 258155 diff --git a/docs/getstarted/images/tips-and-tricks/node_debug.gif b/docs/getstarted/images/tips-and-tricks/node_debug.gif new file mode 100644 index 0000000000000000000000000000000000000000..515550e7529ab1e307b7a0868999bf9520ae00ba --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/node_debug.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:46ececc8320a49474a29286c7df3228df6ea681f2c7bc22b8e86d453085f2886 +size 559886 diff --git a/docs/getstarted/images/tips-and-tricks/package_json_intellisense.gif b/docs/getstarted/images/tips-and-tricks/package_json_intellisense.gif new file mode 100644 index 0000000000000000000000000000000000000000..3894d23a2200f0f0254a55c9b5f2c6f6834c5fcd --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/package_json_intellisense.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:deaa08f11b2bc1116d65c6697428ab575db1b805fce3429a15b5fe26fa29bb64 +size 294665 diff --git a/docs/getstarted/images/tips-and-tricks/peek.gif b/docs/getstarted/images/tips-and-tricks/peek.gif new file mode 100644 index 0000000000000000000000000000000000000000..efcc3ca162201502b0940f9a64b6bc5f351cc0cc --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/peek.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5a27dac8fe1142b0717a487450337688a7c1f497a5ee5689f35aa36dd2147222 +size 471237 diff --git a/docs/getstarted/images/tips-and-tricks/rename_symbol.gif b/docs/getstarted/images/tips-and-tricks/rename_symbol.gif new file mode 100644 index 0000000000000000000000000000000000000000..1e2f173bc0b53741df166c310aa181154a186fe2 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/rename_symbol.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fc173bbd4dc00155fa413a8b14006bca5f0b46d2b64b08dcb125a9dd6fc9ba2e +size 488603 diff --git a/docs/getstarted/images/tips-and-tricks/script_explorer.png b/docs/getstarted/images/tips-and-tricks/script_explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..bf1a4076e385812e9c0dfe4629cf418595a1772a Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/script_explorer.png differ diff --git a/docs/getstarted/images/tips-and-tricks/search_and_modify.png b/docs/getstarted/images/tips-and-tricks/search_and_modify.png new file mode 100644 index 0000000000000000000000000000000000000000..d639966be48bb49578de8178b7144592d9a1b4a5 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/search_and_modify.png differ diff --git a/docs/getstarted/images/tips-and-tricks/show-recommended-extensions.png b/docs/getstarted/images/tips-and-tricks/show-recommended-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..413992f272695859c96c775bbadd9622fe69301d Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/show-recommended-extensions.png differ diff --git a/docs/getstarted/images/tips-and-tricks/shrink_expand_selection.gif b/docs/getstarted/images/tips-and-tricks/shrink_expand_selection.gif new file mode 100644 index 0000000000000000000000000000000000000000..f83dab5ea4da5c75c2f5a7f7d95a7d465b6a4e69 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/shrink_expand_selection.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:74157701d831e5c81df599b80a5bc9b36c5cd9cc27cc637878f599f87f9cb67a +size 239890 diff --git a/docs/getstarted/images/tips-and-tricks/source-control-icon.png b/docs/getstarted/images/tips-and-tricks/source-control-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..a7d6397f0249d22a2b620e9f2f2cdff5e3888708 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/source-control-icon.png differ diff --git a/docs/getstarted/images/tips-and-tricks/split_editor.gif b/docs/getstarted/images/tips-and-tricks/split_editor.gif new file mode 100644 index 0000000000000000000000000000000000000000..26ca3873cbe7360570cb895fef1416b2b2677635 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/split_editor.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b5fd24529a54e5596d477f9bfdb9f47f006d25541de2030708c1d725da825ee3 +size 895505 diff --git a/docs/getstarted/images/tips-and-tricks/status_errors_warnings.png b/docs/getstarted/images/tips-and-tricks/status_errors_warnings.png new file mode 100644 index 0000000000000000000000000000000000000000..7bca0937d877920eb26089a992f598a211eeb15c Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/status_errors_warnings.png differ diff --git a/docs/getstarted/images/tips-and-tricks/switch_branches.gif b/docs/getstarted/images/tips-and-tricks/switch_branches.gif new file mode 100644 index 0000000000000000000000000000000000000000..cb10c5c4b1794f8546eee518abec342c9255e157 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/switch_branches.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:db8dc4f85513c036e938a6f696a082b0b6e587b75e6b299e2c36a1e18a4d3254 +size 298640 diff --git a/docs/getstarted/images/tips-and-tricks/task_runner.gif b/docs/getstarted/images/tips-and-tricks/task_runner.gif new file mode 100644 index 0000000000000000000000000000000000000000..60ec859aa6a8e8b91d44e65f7188de4ff32c8d4a --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/task_runner.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2dfaed5ee11bb4f256573f4832f90f9ad848195e158c8e91b0fea2fba547722d +size 541417 diff --git a/docs/getstarted/images/tips-and-tricks/toggle_side_bar.gif b/docs/getstarted/images/tips-and-tricks/toggle_side_bar.gif new file mode 100644 index 0000000000000000000000000000000000000000..ce6fac99e3955b9f9e88aeb68d75486796b105b7 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/toggle_side_bar.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d4ee85977a3c8f12994d3f1d73a23f44629520d7b885a3dfdb7c4d0136c2a067 +size 558878 diff --git a/docs/getstarted/images/tips-and-tricks/trim_whitespace.gif b/docs/getstarted/images/tips-and-tricks/trim_whitespace.gif new file mode 100644 index 0000000000000000000000000000000000000000..c172900c02d17de065776bacfc02ba1887ed2e95 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/trim_whitespace.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ed6a94f49cef4c467c8857560aa527e736c6e830020433c9e317fd7051f23ff1 +size 232312 diff --git a/docs/getstarted/images/tips-and-tricks/undo_last_commit.gif b/docs/getstarted/images/tips-and-tricks/undo_last_commit.gif new file mode 100644 index 0000000000000000000000000000000000000000..0348699607a32f41fc06db3cdca7ded06802b742 --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/undo_last_commit.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b0e19bfdd640c99e3c111811bb5807a1af29f9a78ccf0c3bd34d00126cf30c41 +size 154546 diff --git a/docs/getstarted/images/tips-and-tricks/welcome_page.png b/docs/getstarted/images/tips-and-tricks/welcome_page.png new file mode 100644 index 0000000000000000000000000000000000000000..0cd8981c4ec3431843278e3c1465d880607a65a0 Binary files /dev/null and b/docs/getstarted/images/tips-and-tricks/welcome_page.png differ diff --git a/docs/getstarted/images/tips-and-tricks/zen_mode.gif b/docs/getstarted/images/tips-and-tricks/zen_mode.gif new file mode 100644 index 0000000000000000000000000000000000000000..1d1da71e8923f06e2d6f338de31dcf5afcb2c9ae --- /dev/null +++ b/docs/getstarted/images/tips-and-tricks/zen_mode.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:22b979a727bed24fb5becd5b6a9961d7f511428b8447121b0ea91e3cb5b2e465 +size 1156579 diff --git a/docs/getstarted/images/userinterface/activity-bar-context-menu.png b/docs/getstarted/images/userinterface/activity-bar-context-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..a48386c22c3b33e9878838fa4785a1c82ab65e84 Binary files /dev/null and b/docs/getstarted/images/userinterface/activity-bar-context-menu.png differ diff --git a/docs/getstarted/images/userinterface/commands.png b/docs/getstarted/images/userinterface/commands.png new file mode 100644 index 0000000000000000000000000000000000000000..4e9a5cddbd52af04cc6a92df6a3e1852a1269097 Binary files /dev/null and b/docs/getstarted/images/userinterface/commands.png differ diff --git a/docs/getstarted/images/userinterface/explorer_menu.png b/docs/getstarted/images/userinterface/explorer_menu.png new file mode 100644 index 0000000000000000000000000000000000000000..ef78eed3eb68787e786c8a0cb013e75c7e319699 Binary files /dev/null and b/docs/getstarted/images/userinterface/explorer_menu.png differ diff --git a/docs/getstarted/images/userinterface/grid-alt.gif b/docs/getstarted/images/userinterface/grid-alt.gif new file mode 100644 index 0000000000000000000000000000000000000000..347f2cda27c3665d6ee7d2760be900a1a19380de Binary files /dev/null and b/docs/getstarted/images/userinterface/grid-alt.gif differ diff --git a/docs/getstarted/images/userinterface/grid-dnd.gif b/docs/getstarted/images/userinterface/grid-dnd.gif new file mode 100644 index 0000000000000000000000000000000000000000..1b6b8b52fcede53d937656bb62abaaf0d0f00049 --- /dev/null +++ b/docs/getstarted/images/userinterface/grid-dnd.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e634b9f50803d471d2157ddfe9cd46139dea27896edc4d3c538cb500e7c59f5b +size 161517 diff --git a/docs/getstarted/images/userinterface/grid-empty.png b/docs/getstarted/images/userinterface/grid-empty.png new file mode 100644 index 0000000000000000000000000000000000000000..efeebd929ff987c69b621ac0674fc424c0d8f0ff Binary files /dev/null and b/docs/getstarted/images/userinterface/grid-empty.png differ diff --git a/docs/getstarted/images/userinterface/grid-layout-menu.png b/docs/getstarted/images/userinterface/grid-layout-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..91550cbc4e2d46e6c60fd3a868f59d82008f59f4 --- /dev/null +++ b/docs/getstarted/images/userinterface/grid-layout-menu.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f81c4d614b873b53586ee8dc04cf939aa17c87fa4763c02ed369137f1b96aa1d +size 142926 diff --git a/docs/getstarted/images/userinterface/grid-layout.gif b/docs/getstarted/images/userinterface/grid-layout.gif new file mode 100644 index 0000000000000000000000000000000000000000..9e6e9eb3d00b3a90d1577b692e41d6376f06f4ab --- /dev/null +++ b/docs/getstarted/images/userinterface/grid-layout.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:917dd27d119160226568b388d8e88a7ef7d2fbe26a1fb3082337209abf591f73 +size 3410812 diff --git a/docs/getstarted/images/userinterface/grid-open-editors.png b/docs/getstarted/images/userinterface/grid-open-editors.png new file mode 100644 index 0000000000000000000000000000000000000000..007b978f21f99cc01016a73bd864a439f07f01fa Binary files /dev/null and b/docs/getstarted/images/userinterface/grid-open-editors.png differ diff --git a/docs/getstarted/images/userinterface/hero.png b/docs/getstarted/images/userinterface/hero.png new file mode 100644 index 0000000000000000000000000000000000000000..79330e1d086d16acd6948ee6bdb38c6ba05ca269 --- /dev/null +++ b/docs/getstarted/images/userinterface/hero.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:47b7c52182a51ef7ca91ea16c9309cd17fdb57d572b281f16db2554f4622dd9e +size 345150 diff --git a/docs/getstarted/images/userinterface/markdown-outline-view.png b/docs/getstarted/images/userinterface/markdown-outline-view.png new file mode 100644 index 0000000000000000000000000000000000000000..7cf919116445a234f5b28cd9f861c4767e4c1492 Binary files /dev/null and b/docs/getstarted/images/userinterface/markdown-outline-view.png differ diff --git a/docs/getstarted/images/userinterface/minimap.png b/docs/getstarted/images/userinterface/minimap.png new file mode 100644 index 0000000000000000000000000000000000000000..9dd77646f3fe6c362ff8f06a458a730d78a05c4b Binary files /dev/null and b/docs/getstarted/images/userinterface/minimap.png differ diff --git a/docs/getstarted/images/userinterface/outline-view.png b/docs/getstarted/images/userinterface/outline-view.png new file mode 100644 index 0000000000000000000000000000000000000000..77315c2c7bb5224795e9e6042b3a397bef0ecf2f Binary files /dev/null and b/docs/getstarted/images/userinterface/outline-view.png differ diff --git a/docs/getstarted/images/userinterface/preview-tab.png b/docs/getstarted/images/userinterface/preview-tab.png new file mode 100644 index 0000000000000000000000000000000000000000..4816ff1152ee82a2861d9f08244896e6e5999d7a Binary files /dev/null and b/docs/getstarted/images/userinterface/preview-tab.png differ diff --git a/docs/getstarted/images/userinterface/quickopenhelp.png b/docs/getstarted/images/userinterface/quickopenhelp.png new file mode 100644 index 0000000000000000000000000000000000000000..756c535e2bd28ae01f765f8d80d47cc799e64523 Binary files /dev/null and b/docs/getstarted/images/userinterface/quickopenhelp.png differ diff --git a/docs/getstarted/images/userinterface/sidebyside.png b/docs/getstarted/images/userinterface/sidebyside.png new file mode 100644 index 0000000000000000000000000000000000000000..3cd72fad0451ec221e7ecb1475853e6ea1115d2c --- /dev/null +++ b/docs/getstarted/images/userinterface/sidebyside.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:35635f91b1c2ec801420f161b175a7d321a7982451a1d128017c92bb31a86082 +size 240759 diff --git a/docs/getstarted/images/userinterface/tabs-editor-groups.png b/docs/getstarted/images/userinterface/tabs-editor-groups.png new file mode 100644 index 0000000000000000000000000000000000000000..880d266290d3f05942e5b903f64198f9c211e063 --- /dev/null +++ b/docs/getstarted/images/userinterface/tabs-editor-groups.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:47030cedd8057c91873aea814ad56ca08dfd92b7bafd3d84457b6488493c97de +size 112784 diff --git a/docs/getstarted/images/userinterface/tabs-hero.png b/docs/getstarted/images/userinterface/tabs-hero.png new file mode 100644 index 0000000000000000000000000000000000000000..67ff9c61ccc7a043e875c053a9bfbd275bb18899 Binary files /dev/null and b/docs/getstarted/images/userinterface/tabs-hero.png differ diff --git a/docs/getstarted/images/userinterface/view-management.png b/docs/getstarted/images/userinterface/view-management.png new file mode 100644 index 0000000000000000000000000000000000000000..57a3656a965dc1de9f6e27ca21c1aa5af2a15bf5 --- /dev/null +++ b/docs/getstarted/images/userinterface/view-management.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:84cd2d993d5a982b41642dbb4a01a04f6b982a63c807f649d2b4f57fc0ca7ceb +size 159120 diff --git a/docs/getstarted/images/userinterface/views.png b/docs/getstarted/images/userinterface/views.png new file mode 100644 index 0000000000000000000000000000000000000000..d43c3b7d12ea2dc95dae95ca0796976365074927 Binary files /dev/null and b/docs/getstarted/images/userinterface/views.png differ diff --git a/docs/getstarted/images/userinterface/workspace-settings.png b/docs/getstarted/images/userinterface/workspace-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..717e92618bc9d26d8ab84d9a3752c5596a6bb236 --- /dev/null +++ b/docs/getstarted/images/userinterface/workspace-settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6866973e2050e95067c0fa515c8c73874b9c992863808974db3af3dbb6cdcb04 +size 196257 diff --git a/docs/getstarted/introvideos.md b/docs/getstarted/introvideos.md new file mode 100644 index 0000000000000000000000000000000000000000..77daa604647a78b8a1a041842cdc181f229dff69 --- /dev/null +++ b/docs/getstarted/introvideos.md @@ -0,0 +1,88 @@ +--- +Order: 2 +Area: getstarted +TOCTitle: Intro Videos +ContentId: f29747b9-0f4f-4f62-b0a7-037ffc49d972 +PageTitle: Visual Studio Code Introductory Videos +DateApproved: 3/7/2019 +MetaDescription: Overview of Visual Studio Code's introductory videos. +MetaSocialImage: images/introvideos/opengraph_introvideos.png +--- +# Introductory Videos + +Start your journey with Visual Studio Code with this set of introductory videos. The videos are designed to give you a quick overview of the various features of VS Code. VS Code comes with JavaScript and TypeScript support out of the box so the videos use JavaScript in the examples. + + + +> Note: If you would like us to cover other topics, please leave [feedback here](https://www.surveymonkey.com/r/H9W7K8J). diff --git a/docs/getstarted/keybindings.md b/docs/getstarted/keybindings.md new file mode 100644 index 0000000000000000000000000000000000000000..cc65a59ad50cf0725d45dd04e93a8f3122b90f54 --- /dev/null +++ b/docs/getstarted/keybindings.md @@ -0,0 +1,619 @@ +--- +Order: 7 +Area: getstarted +TOCTitle: Key Bindings +ContentId: 045980C1-62C7-4E8E-8CE4-BAD722FFE31E +PageTitle: Visual Studio Code Key Bindings +DateApproved: 3/7/2019 +MetaDescription: Here you will find the complete list of key bindings for Visual Studio Code and how to change them. +MetaSocialImage: images/keybinding/customization_keybindings.png +--- +# Key Bindings for Visual Studio Code + +Visual Studio Code lets you perform most tasks directly from the keyboard. This page lists out the default bindings (keyboard shortcuts) and describes how you can update them. + +>**Note:** If you visit this page on a Mac, you will see the key bindings for the Mac. If you visit using Windows or Linux, you will see the keys for that platform. If you need the key binding for another platform, hover your mouse over the key you are interested in. + +## Keyboard Shortcuts editor + +Visual Studio Code provides a rich and easy keyboard shortcuts editing experience using **Keyboard Shortcuts** editor. It lists all available commands with and without keybindings and you can easily change / remove / reset their keybindings using the available actions. It also has a search box on the top that helps you in finding commands or keybindings. You can open this editor by going to the menu under **File** > **Preferences** > **Keyboard Shortcuts**. (**Code** > **Preferences** > **Keyboard Shortcuts** on macOS) + +![Keyboard Shortcuts](images/keybinding/keyboard-shortcuts.gif) + +Most importantly, you can see keybindings according to your keyboard layout. For example, key binding `kbstyle(Cmd+\)` in US keyboard layout will be shown as `kbstyle(Ctrl+Shift+Alt+Cmd+7)` when layout is changed to German. The dialog to enter key binding will assign the correct and desired key binding as per your keyboard layout. + +For doing more advanced keyboard shortcut customization, read [Advanced Customization](/docs/getstarted/keybindings.md#advanced-customization). + +## Keymap extensions + +Keyboard shortcuts are vital to productivity and changing keyboarding habits can be tough. To help with this, **File** > **Preferences** > **Keymap Extensions** shows you a list of popular keymap extensions. These extensions modify the VS Code shortcuts to match those of other editors so you don't need to learn new keyboard shortcuts. There is also a [Keymaps category](https://marketplace.visualstudio.com/search?target=VSCode&category=Keymaps&sortBy=Downloads) of extensions in the Marketplace. + +
+ +> Tip: Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com/vscode). + +## Keyboard Shortcuts Reference + +We also have a printable version of these keyboard shortcuts. **Help** > **Keyboard Shortcut Reference** displays a condensed PDF version suitable for printing as an easy reference. + +Below are links to the three platform-specific versions: + +* [Windows](https://go.microsoft.com/fwlink/?linkid=832145) +* [macOS](https://go.microsoft.com/fwlink/?linkid=832143) +* [Linux](https://go.microsoft.com/fwlink/?linkid=832144) + +## Detecting keybinding conflicts + +If you have many extensions installed or you have [customized](/docs/getstarted/keybindings.md#advanced-customization) your keyboard shortcuts, you can sometimes have keybinding conflicts where the same keyboard shortcut is mapped to several commands. This can result in confusing behavior, especially if different keybindings are going in and out of scope as you move around the editor. + +The **Keyboard Shortcuts** editor has a context menu command **Show Conflicts**, which will filter the keybindings based on a keyboard shortcut to display conflicts. + +![show keybinding conflicts menu](images/keybinding/show-conflicts-menu.png) + +Pick a command with the keybinding you think is overloaded and you can see if multiple commands are defined, the source of the keybindings and when they are active. + +![show keybinding conflicts result](images/keybinding/show-conflicts-result.png) + +## Advanced customization + +All keyboard shortcuts in VS Code can be customized via the `keybindings.json` file. + +* To configure keyboard shortcuts the way you want, open **Keyboard Shortcuts** editor and click on the link `keybindings.json`. +* This will open the **Default Keyboard Shortcuts** on the left and your `keybindings.json` file where you can overwrite the default bindings on the right. +* The list above isn't exhaustive. More commands may be listed under "Here are other available commands" in **Default Keyboard Shortcuts**. + +## Keyboard rules + +The keyboard shortcuts dispatching is done by analyzing a list of rules that are expressed in JSON. Here are some examples: + +```json +// Keybindings that are active when the focus is in the editor +{ "key": "home", "command": "cursorHome", "when": "editorTextFocus" }, +{ "key": "shift+home", "command": "cursorHomeSelect", "when": "editorTextFocus" }, + +// Keybindings that are complementary +{ "key": "f5", "command": "workbench.action.debug.continue", "when": "inDebugMode" }, +{ "key": "f5", "command": "workbench.action.debug.start", "when": "!inDebugMode" }, + +// Global keybindings +{ "key": "ctrl+f", "command": "actions.find" }, +{ "key": "alt+left", "command": "workbench.action.navigateBack" }, +{ "key": "alt+right", "command": "workbench.action.navigateForward" }, + +// Global keybindings using chords (two separate keypress actions) +{ "key": "ctrl+k enter", "command": "workbench.action.keepEditor" }, +{ "key": "ctrl+k ctrl+w", "command": "workbench.action.closeAllEditors" }, +``` + +Each rule consists of: + +* a `key` that describes the pressed keys. +* a `command` containing the identifier of the command to execute. +* an **optional** `when` clause containing a boolean expression that will be evaluated depending on the current **context**. + +Chords (two separate keypress actions) are described by separating the two keypresses with a space. For example, `kbstyle(Ctrl+K Ctrl+C)`. + +When a key is pressed: + +* the rules are evaluated from **bottom** to **top**. +* the first rule that matches, both the `key` and in terms of `when`, is accepted. +* no more rules are processed. +* if a rule is found and has a `command` set, the `command` is executed. + +The additional `keybindings.json` rules are appended at runtime to the bottom of the default rules, thus allowing them to overwrite the default rules. The `keybindings.json` file is watched by VS Code so editing it while VS Code is running will update the rules at runtime. + +## Accepted keys + +The `key` is made up of modifiers and the key itself. + +The following modifiers are accepted: + +Platform|Modifiers +--|--------- +macOS|`kbstyle(Ctrl+)`, `kbstyle(Shift+)`, `kbstyle(Alt+)`, `kbstyle(Cmd+)` +Windows|`kbstyle(Ctrl+)`, `kbstyle(Shift+)`, `kbstyle(Alt+)`, `kbstyle(Win+)` +Linux|`kbstyle(Ctrl+)`, `kbstyle(Shift+)`, `kbstyle(Alt+)`, `kbstyle(Meta+)` + +The following keys are accepted: + +* `kbstyle(f1-f19)`, `kbstyle(a-z)`, `kbstyle(0-9)` +* ``kbstyle(`)``, `kbstyle(-)`, `kbstyle(=)`, `kbstyle([)`, `kbstyle(])`, `kbstyle(\)`, `kbstyle(;)`, `kbstyle(')`, `kbstyle(,)`, `kbstyle(.)`, `kbstyle(/)` +* `kbstyle(left)`, `kbstyle(up)`, `kbstyle(right)`, `kbstyle(down)`, `kbstyle(pageup)`, `kbstyle(pagedown)`, `kbstyle(end)`, `kbstyle(home)` +* `kbstyle(tab)`, `kbstyle(enter)`, `kbstyle(escape)`, `kbstyle(space)`, `kbstyle(backspace)`, `kbstyle(delete)` +* `kbstyle(pausebreak)`, `kbstyle(capslock)`, `kbstyle(insert)` +* `kbstyle(numpad0-numpad9)`, `kbstyle(numpad_multiply)`, `kbstyle(numpad_add)`, `kbstyle(numpad_separator)` +* `kbstyle(numpad_subtract)`, `kbstyle(numpad_decimal)`, `kbstyle(numpad_divide)` + +## Command arguments + +You can invoke a command with arguments. This is useful if you often perform the same operation on a specific file or folder. You can add a custom keyboard shortcut to do exactly what you want. + +The following is an example overriding the `kbstyle(Enter)` key to print some text: + +```json + { "key": "enter", "command": "type", + "args": { "text": "Hello World" }, + "when": "editorTextFocus" } +``` + +The type command will receive `{"text": "Hello World"}` as its first argument and add "Hello World" to the file instead of producing the default command. + +For more information on commands that take arguments, refer to [Built-in Commands](/api/references/commands.md). + +## Removing a specific key binding rule + +You can write a key binding rule that targets the removal of a specific default key binding. With the `keybindings.json`, it was always possible to redefine all the key bindings of VS Code, but it can be very difficult to make a small tweak, especially around overloaded keys, such as `kbstyle(Tab)` or `kbstyle(Escape)`. To remove a specific key binding, add a `-` to the `command` and the rule will be a removal rule. + +Here is an example: + +```json +// In Default Keyboard Shortcuts +... +{ "key": "tab", "command": "tab", "when": ... }, +{ "key": "tab", "command": "jumpToNextSnippetPlaceholder", "when": ... }, +{ "key": "tab", "command": "acceptSelectedSuggestion", "when": ... }, +... + +// To remove the second rule, for example, add in keybindings.json: +{ "key": "tab", "command": "-jumpToNextSnippetPlaceholder" } + +``` + +## Keyboard layouts + +>**Note:** This section relates only to key bindings, not to typing in the editor. + +The keys above are string representations for virtual keys and do not necessarily relate to the produced character when they are pressed. More precisely: + +* Reference: [Virtual-Key Codes (Windows)](https://msdn.microsoft.com/library/windows/desktop/dd375731) +* `kbstyle(tab)` for `VK_TAB` (`0x09`) +* `kbstyle(;)` for `VK_OEM_1` (`0xBA`) +* `kbstyle(=)` for `VK_OEM_PLUS` (`0xBB`) +* `kbstyle(,)` for `VK_OEM_COMMA` (`0xBC`) +* `kbstyle(-)` for `VK_OEM_MINUS` (`0xBD`) +* `kbstyle(.)` for `VK_OEM_PERIOD` (`0xBE`) +* `kbstyle(/)` for `VK_OEM_2` (`0xBF`) +* ``kbstyle(`)`` for `VK_OEM_3` (`0xC0`) +* `kbstyle([)` for `VK_OEM_4` (`0xDB`) +* `kbstyle(\)` for `VK_OEM_5` (`0xDC`) +* `kbstyle(])` for `VK_OEM_6` (`0xDD`) +* `kbstyle(')` for `VK_OEM_7` (`0xDE`) +* etc. + +Different keyboard layouts usually reposition the above virtual keys or change the characters produced when they are pressed. When using a different keyboard layout than the standard US, Visual Studio Code does the following: + +All the key bindings are rendered in the UI using the current system's keyboard layout. For example, `Split Editor` when using a French (France) keyboard layout is now rendered as `kbstyle(Ctrl+*)`: + +![render key binding](images/keybinding/render-key-binding.png) + +When editing `keybindings.json`, VS Code highlights misleading key bindings - those that are represented in the file with the character produced under the standard US keyboard layout, but which need pressing keys with different labels under the current system's keyboard layout. For example, here is how the **Default Keyboard Shortcuts** rules look like when using a French (France) keyboard layout: + +![keybindings.json guidance](images/keybinding/keybindings-json.png) + +There is also a widget that helps input the key binding rule when editing `keybindings.json`. To launch the **Define Keybinding** widget, press `kb(editor.action.defineKeybinding)`. The widget listens for key presses and renders the serialized JSON representation in the text box and below it, the keys that VS Code has detected under your current keyboard layout. Once you've typed the key combination you want, you can press `kbstyle(Enter)` and a rule snippet will be inserted. + +![key binding widget](images/keybinding/key-binding-widget.png) + +>**Note:** On Linux, Visual Studio Code detects your current keyboard layout on start-up and then caches this information. For a good experience, we recommend restarting VS Code if you change your keyboard layout. + +## Keyboard layout independent bindings + +Using scan codes, it is possible to define keybindings which do not change with the change of the keyboard layout. For example: + +```json +{ "key": "cmd+[Slash]", "command": "editor.action.commentLine", + "when": "editorTextFocus" } +``` + +Accepted scan codes: + +* `kbstyle([F1]-[F19])`, `kbstyle([KeyA]-[KeyZ])`, `kbstyle([Digit0]-[Digit9])` +* `kbstyle([Backquote])`, `kbstyle([Minus])`, `kbstyle([Equal])`, `kbstyle([BracketLeft])`, `kbstyle([BracketRight])`, `kbstyle([Backslash])`, `kbstyle([Semicolon])`, `kbstyle([Quote])`, `kbstyle([Comma])`, `kbstyle([Period])`, `kbstyle([Slash])` +* `kbstyle([ArrowLeft])`, `kbstyle([ArrowUp])`, `kbstyle([ArrowRight])`, `kbstyle([ArrowDown])`, `kbstyle([PageUp])`, `kbstyle([PageDown])`, `kbstyle([End])`, `kbstyle([Home])` +* `kbstyle([Tab])`, `kbstyle([Enter])`, `kbstyle([Escape])`, `kbstyle([Space])`, `kbstyle([Backspace])`, `kbstyle([Delete])` +* `kbstyle([Pause])`, `kbstyle([CapsLock])`, `kbstyle([Insert])` +* `kbstyle([Numpad0]-[Numpad9])`, `kbstyle([NumpadMultiply])`, `kbstyle([NumpadAdd])`, `kbstyle([NumpadComma])` +* `kbstyle([NumpadSubtract])`, `kbstyle([NumpadDecimal])`, `kbstyle([NumpadDivide])` + +## 'when' clause contexts + +VS Code gives you fine control over when your key bindings are enabled through the optional `when` clause. If your key binding doesn't have a `when` clause, the key binding is globally available at all times. + +Below are the some of the possible `when` clause contexts which evaluate to Boolean true/false. For conditional expressions, you can use either equality `==` (`"editorLangId == typescript"`) or inequality `!=` (`"resourceExtname != .js"`). + +Context name | True when +------------ | ------------ +**Editor contexts** | +editorFocus | An editor has focus, either the text or a widget. +editorTextFocus | The text in an editor has focus (cursor is blinking). +textInputFocus | Any editor has focus (regular editor, debug REPL, etc.). +inputFocus | Any text input area has focus (editors or text boxes). +editorHasSelection | Text is selected in the editor. +editorHasMultipleSelections | Multiple regions of text are selected (multiple cursors). +editorReadOnly | The editor is read only. +editorLangId | True when the editor's associated [language Id](/docs/languages/identifiers.md) matches. Example: `"editorLangId == typescript"`. +isInDiffEditor | The active editor is a difference editor. +**Operating system contexts** | +isLinux | True when the OS is Linux +isMac | True when the OS is macOS +isWindows | True when the OS is Windows +**Mode contexts** | +inDebugMode | A debug session is running. +debugType | True when debug type matches. Example: `"debugType == 'node'"`. +inSnippetMode | The editor is in snippet mode. +inQuickOpen | The Quick Open drop-down has focus. +**Resource contexts** | +resourceScheme | True when the resource Uri scheme matches. Example: `"resourceScheme == file"` +resourceFilename | True when the Explorer or editor filename matches. Example: `"resourceFilename == gulpfile.js"` +resourceExtname | True when the Explorer or editor filename extension matches. Example: `"resourceExtname == .js"` +resourceLangId | True when the Explorer or editor title [language Id](/docs/languages/identifiers.md) matches. Example: `"resourceLangId == markdown"` +**Explorer contexts** | +explorerViewletVisible | True if Explorer view is visible. +explorerViewletFocus | True if Explorer view has keyboard focus. +filesExplorerFocus | True if File Explorer section has keyboard focus. +openEditorsFocus | True if OPEN EDITORS section has keyboard focus. +explorerResourceIsFolder | True if a folder is selected in the Explorer. +**Editor widget contexts** | +findWidgetVisible | Editor Find widget is visible. +suggestWidgetVisible | Suggestion widget (IntelliSense) is visible. +suggestWidgetMultipleSuggestions | Multiple suggestions are displayed. +renameInputVisible | Rename input text box is visible. +referenceSearchVisible | Peek References peek window is open. +inReferenceSearchEditor | The Peek References peek window editor has focus. +config.editor.stablePeek | Keep peek editors open (controlled by `editor.stablePeek` setting). +quickFixWidgetVisible | Quick Fix widget is visible. +parameterHintsVisible | Parameter hints are visible (controlled by `editor.parameterHints` setting). +parameterHintsMultipleSignatures | Multiple parameter hints are displayed. +**Integrated terminal contexts** | +terminalFocus | An integrated terminal has focus. +**Global UI contexts** | +notificationFocus | Notification has keyboard focus. +notificationCenterVisible | Notification Center is visible at the bottom right of VS Code. +notificationToastsVisible | Notification toast is visible at the bottom right of VS Code. +searchViewletVisible | Search view is open. +sidebarVisible | Side Bar is displayed. +sideBarFocus | Side Bar has focus. +panelFocus | Panel has focus. +editorIsOpen | True if one editor is open. +inZenMode | Window is in Zen Mode. +inDebugRepl | Focus is in the Debug Console REPL. +textCompareEditorVisible | At least one diff (compare) view is visible. +workspaceFolderCount | Count of workspace folders. +replaceActive | Search view Replace text box is open. +view | True when view identifier matches. Example: `"view == myViewsExplorerID"`. +viewItem | True when viewItem context matches. Example: `"viewItem == someContextValue"`. +**Configuration settings contexts** | +config.editor.minimap.enabled | True when the setting `editor.minimap.enabled` is `true`. + +>**Note**: You can use any user or workspace setting that evaluates to a boolean here with the prefix `"config."`. + +The list above isn't exhaustive and you may see some `when` contexts for specific VS Code UI in the **Default Keyboard Shortcuts**. + +### Active/Focused view or panel 'when' clause context + +You can have a keybinding that is enabled only when a specific view or panel is visible. + +Context name | True when +------------ | ------------ +activeViewlet | True when view is visible. Example: `"activeViewlet == 'workbench.view.explorer'"` +activePanel | True when panel is visible. Example: `"activePanel == 'workbench.panel.output'"` + +View Identifiers: + +* workbench.view.explorer - File Explorer +* workbench.view.search - Search +* workbench.view.scm - Source Control +* workbench.view.debug - Debug +* workbench.view.extensions - Extensions + +Panel Identifiers: + +* workbench.panel.markers - Problems +* workbench.panel.output - Output +* workbench.panel.repl - Debug Console +* workbench.panel.terminal - Integrated Terminal +* workbench.panel.comments - Comments +* workbench.view.search - Search when `search.location` is set to `panel` + +If you want a keybinding that is enabled only when a specific view or panel has focus, use `sideBarFocus` or `panelFocus` in combination with `activeViewlet` or `activiewFocus`. + +For example, the when clause below is true only when the File Explorer has focus: + +```json +"sideBarFocus && activeViewlet == 'workbench.view.explorer'" +``` + +### key-value when clause operator + +There is a key-value pair operator for `when` clauses. The expression `key =~ value` treats the right hand side as a regular expression to match against the left hand side. For example, to contribute context menu items for all Docker files, one could use: + +```json + "when": "resourceFilename =~ /docker/" +``` + +## Custom keybindings for refactorings + +The `editor.action.codeAction` command lets you configure keybindings for specific [Refactorings](/docs/editor/refactoring.md) (Code Actions). For example, the keybinding below triggers the **Extract function** refactoring Code Actions: + +```json +{ + "key": "ctrl+shift+r ctrl+e", + "command": "editor.action.codeAction", + "args": { + "kind": "refactor.extract.function" + } +} +``` + +This is covered in depth in the [Refactoring](/docs/editor/refactoring.md#keybindings-for-code-actions) topic where you can learn about different kinds of Code Actions and how to prioritize them in the case of multiple possible refactorings. + +## Default Keyboard Shortcuts + +>**Note:** The following keys are rendered assuming a standard US keyboard layout. If you use a different keyboard layout, please [read below](/docs/getstarted/keybindings.md#keyboard-layouts). You can view the currently active keyboard shortcuts in VS Code in the **Command Palette** (**View** -> **Command Palette**) or in the **Keyboard Shortcuts** editor (**File** > **Preferences** > **Keyboard Shortcuts**). + +Some commands included below do not have default keyboard shortcuts (`kbstyle(unassigned)`) but you can assign your own keybindings. + +### Basic Editing + +Key|Command|Command id +---|-------|---------- +`kb(editor.action.clipboardCutAction)`|Cut line (empty selection)|`editor.action.clipboardCutAction` +`kb(editor.action.clipboardCopyAction)`|Copy line (empty selection)|`editor.action.clipboardCopyAction` +`kb(editor.action.deleteLines)`|Delete Line|`editor.action.deleteLines` +`kb(editor.action.insertLineAfter)`|Insert Line Below|`editor.action.insertLineAfter` +`kb(editor.action.insertLineBefore)`|Insert Line Above|`editor.action.insertLineBefore` +`kb(editor.action.moveLinesDownAction)`|Move Line Down|`editor.action.moveLinesDownAction` +`kb(editor.action.moveLinesUpAction)`|Move Line Up|`editor.action.moveLinesUpAction` +`kb(editor.action.copyLinesDownAction)`|Copy Line Down|`editor.action.copyLinesDownAction` +`kb(editor.action.copyLinesUpAction)`|Copy Line Up|`editor.action.copyLinesUpAction` +`kb(editor.action.addSelectionToNextFindMatch)`|Add Selection To Next Find Match|`editor.action.addSelectionToNextFindMatch` +`kb(editor.action.moveSelectionToNextFindMatch)`|Move Last Selection To Next Find Match|`editor.action.moveSelectionToNextFindMatch` +`kb(cursorUndo)`|Undo last cursor operation|`cursorUndo` +`kb(editor.action.insertCursorAtEndOfEachLineSelected)`|Insert cursor at end of each line selected|`editor.action.insertCursorAtEndOfEachLineSelected` +`kb(editor.action.selectHighlights)`|Select all occurrences of current selection|`editor.action.selectHighlights` +`kb(editor.action.changeAll)`|Select all occurrences of current word|`editor.action.changeAll` +`kb(expandLineSelection)`|Select current line|`expandLineSelection` +`kb(editor.action.insertCursorBelow)`|Insert Cursor Below|`editor.action.insertCursorBelow` +`kb(editor.action.insertCursorAbove)`|Insert Cursor Above|`editor.action.insertCursorAbove` +`kb(editor.action.jumpToBracket)`|Jump to matching bracket|`editor.action.jumpToBracket` +`kb(editor.action.indentLines)`|Indent Line|`editor.action.indentLines` +`kb(editor.action.outdentLines)`|Outdent Line|`editor.action.outdentLines` +`kb(cursorHome)`|Go to Beginning of Line|`cursorHome` +`kb(cursorEnd)`|Go to End of Line|`cursorEnd` +`kb(cursorBottom)`|Go to End of File|`cursorBottom` +`kb(cursorTop)`|Go to Beginning of File|`cursorTop` +`kb(scrollLineDown)`|Scroll Line Down|`scrollLineDown` +`kb(scrollLineUp)`|Scroll Line Up|`scrollLineUp` +`kb(scrollPageDown)`|Scroll Page Down|`scrollPageDown` +`kb(scrollPageUp)`|Scroll Page Up|`scrollPageUp` +`kb(editor.fold)`|Fold (collapse) region|`editor.fold` +`kb(editor.unfold)`|Unfold (uncollapse) region|`editor.unfold` +`kb(editor.foldRecursively)`|Fold (collapse) all subregions|`editor.foldRecursively` +`kb(editor.unfoldRecursively)`|Unfold (uncollapse) all subregions|`editor.unfoldRecursively` +`kb(editor.foldAll)`|Fold (collapse) all regions|`editor.foldAll` +`kb(editor.unfoldAll)`|Unfold (uncollapse) all regions|`editor.unfoldAll` +`kb(editor.action.addCommentLine)`|Add Line Comment|`editor.action.addCommentLine` +`kb(editor.action.removeCommentLine)`|Remove Line Comment|`editor.action.removeCommentLine` +`kb(editor.action.commentLine)`|Toggle Line Comment|`editor.action.commentLine` +`kb(editor.action.blockComment)`|Toggle Block Comment|`editor.action.blockComment` +`kb(actions.find)`|Find|`actions.find` +`kb(editor.action.startFindReplaceAction)`|Replace|`editor.action.startFindReplaceAction` +`kb(editor.action.nextMatchFindAction)`|Find Next|`editor.action.nextMatchFindAction` +`kb(editor.action.previousMatchFindAction)`|Find Previous|`editor.action.previousMatchFindAction` +`kb(editor.action.selectAllMatches)`|Select All Occurrences of Find Match|`editor.action.selectAllMatches` +`kb(toggleFindCaseSensitive)`|Toggle Find Case Sensitive|`toggleFindCaseSensitive` +`kb(toggleFindRegex)`|Toggle Find Regex|`toggleFindRegex` +`kb(toggleFindWholeWord)`|Toggle Find Whole Word|`toggleFindWholeWord` +`kb(editor.action.toggleTabFocusMode)`|Toggle Use of Tab Key for Setting Focus|`editor.action.toggleTabFocusMode` +`kb(toggleRenderWhitespace)`|Toggle Render Whitespace|`toggleRenderWhitespace` +`kb(editor.action.toggleWordWrap)`|Toggle Word Wrap|`editor.action.toggleWordWrap` + +### Rich Languages Editing + +Key|Command|Command id +---|-------|---------- +`kb(editor.action.triggerSuggest)`|Trigger Suggest|`editor.action.triggerSuggest` +`kb(editor.action.triggerParameterHints)`|Trigger Parameter Hints|`editor.action.triggerParameterHints` +`kb(editor.action.formatDocument)`|Format Document|`editor.action.formatDocument` +`kb(editor.action.formatSelection)`|Format Selection|`editor.action.formatSelection` +`kb(editor.action.revealDefinition)`|Go to Definition|`editor.action.revealDefinition` +`kb(editor.action.showHover)`|Show Hover|`editor.action.showHover` +`kb(editor.action.peekDefinition)`|Peek Definition|`editor.action.peekDefinition` +`kb(editor.action.revealDefinitionAside)`|Open Definition to the Side|`editor.action.revealDefinitionAside` +`kb(editor.action.quickFix)`|Quick Fix|`editor.action.quickFix` +`kb(editor.action.referenceSearch.trigger)`|Peek References|`editor.action.referenceSearch.trigger` +`kb(editor.action.rename)`|Rename Symbol|`editor.action.rename` +`kb(editor.action.inPlaceReplace.down)`|Replace with Next Value|`editor.action.inPlaceReplace.down` +`kb(editor.action.inPlaceReplace.up)`|Replace with Previous Value|`editor.action.inPlaceReplace.up` +`kb(editor.action.smartSelect.expand)`|Expand AST Selection|`editor.action.smartSelect.expand` +`kb(editor.action.smartSelect.shrink)`|Shrink AST Selection|`editor.action.smartSelect.shrink` +`kb(editor.action.trimTrailingWhitespace)`|Trim Trailing Whitespace|`editor.action.trimTrailingWhitespace` +`kb(workbench.action.editor.changeLanguageMode)`|Change Language Mode|`workbench.action.editor.changeLanguageMode` + +### Navigation + +Key|Command|Command id +---|-------|---------- +`kb(workbench.action.showAllSymbols)`|Show All Symbols|`workbench.action.showAllSymbols` +`kb(workbench.action.gotoLine)`|Go to Line...|`workbench.action.gotoLine` +`kb(workbench.action.quickOpen)`|Go to File..., Quick Open|`workbench.action.quickOpen` +`kb(workbench.action.gotoSymbol)`|Go to Symbol...|`workbench.action.gotoSymbol` +`kb(workbench.actions.view.problems)`|Show Problems|`workbench.actions.view.problems` +`kb(editor.action.marker.nextInFiles)`|Go to Next Error or Warning|`editor.action.marker.nextInFiles` +`kb(editor.action.marker.prevInFiles)`|Go to Previous Error or Warning|`editor.action.marker.prevInFiles` +`kb(workbench.action.showCommands)`|Show All Commands|`workbench.action.showCommands` +`kb(workbench.action.openPreviousRecentlyUsedEditorInGroup)`|Navigate Editor Group History|`workbench.action.openPreviousRecentlyUsedEditorInGroup` +`kb(workbench.action.navigateBack)`|Go Back|`workbench.action.navigateBack` +`kb(workbench.action.quickInputBack)`|Go back in Quick Input|`workbench.action.quickInputBack` +`kb(workbench.action.navigateForward)`|Go Forward|`workbench.action.navigateForward` + +### Editor/Window Management + +Key|Command|Command id +---|-------|---------- +`kb(workbench.action.newWindow)`|New Window|`workbench.action.newWindow` +`kb(workbench.action.closeWindow)`|Close Window|`workbench.action.closeWindow` +`kb(workbench.action.closeActiveEditor)`|Close Editor|`workbench.action.closeActiveEditor` +`kb(workbench.action.closeFolder)`|Close Folder|`workbench.action.closeFolder` +`kb(workbench.action.navigateEditorGroups)`|Cycle Between Editor Groups|`workbench.action.navigateEditorGroups` +`kb(workbench.action.splitEditor)`|Split Editor|`workbench.action.splitEditor` +`kb(workbench.action.focusFirstEditorGroup)`|Focus into First Editor Group|`workbench.action.focusFirstEditorGroup` +`kb(workbench.action.focusSecondEditorGroup)`|Focus into Second Editor Group|`workbench.action.focusSecondEditorGroup` +`kb(workbench.action.focusThirdEditorGroup)`|Focus into Third Editor Group|`workbench.action.focusThirdEditorGroup` +`kb(workbench.action.focusPreviousGroup)`|Focus into Editor Group on the Left|`workbench.action.focusPreviousGroup` +`kb(workbench.action.focusNextGroup)`|Focus into Editor Group on the Right|`workbench.action.focusNextGroup` +`kb(workbench.action.moveEditorLeftInGroup)`| Move Editor Left |`workbench.action.moveEditorLeftInGroup` +`kb(workbench.action.moveEditorRightInGroup)`| Move Editor Right |`workbench.action.moveEditorRightInGroup` +`kb(workbench.action.moveActiveEditorGroupLeft)`|Move Active Editor Group Left|`workbench.action.moveActiveEditorGroupLeft` +`kb(workbench.action.moveActiveEditorGroupRight)`|Move Active Editor Group Right|`workbench.action.moveActiveEditorGroupRight` +`kb(workbench.action.moveEditorToNextGroup)`|Move Editor into Next Group|`workbench.action.moveEditorToNextGroup` +`kb(workbench.action.moveEditorToPreviousGroup)`|Move Editor into Previous Group|`workbench.action.moveEditorToPreviousGroup` + +### File Management + +Key|Command|Command id +---|-------|---------- +`kb(workbench.action.files.newUntitledFile)`|New File|`workbench.action.files.newUntitledFile` +`kb(workbench.action.files.openFile)`|Open File...|`workbench.action.files.openFile` +`kb(workbench.action.files.save)`|Save|`workbench.action.files.save` +`kb(workbench.action.files.saveAll)`|Save All|`workbench.action.files.saveAll` +`kb(workbench.action.files.saveAs)`|Save As...|`workbench.action.files.saveAs` +`kb(workbench.action.closeActiveEditor)`|Close|`workbench.action.closeActiveEditor` +`kb(workbench.action.closeOtherEditors)`|Close Others|`workbench.action.closeOtherEditors` +`kb(workbench.action.closeEditorsInGroup)`|Close Group|`workbench.action.closeEditorsInGroup` +`kb(workbench.action.closeEditorsInOtherGroups)`|Close Other Groups|`workbench.action.closeEditorsInOtherGroups` +`kb(workbench.action.closeEditorsToTheLeft)`|Close Group to Left|`workbench.action.closeEditorsToTheLeft` +`kb(workbench.action.closeEditorsToTheRight)`|Close Group to Right|`workbench.action.closeEditorsToTheRight` +`kb(workbench.action.closeAllEditors)`|Close All|`workbench.action.closeAllEditors` +`kb(workbench.action.reopenClosedEditor)`|Reopen Closed Editor|`workbench.action.reopenClosedEditor` +`kb(workbench.action.keepEditor)`|Keep Open|`workbench.action.keepEditor` +`kb(workbench.action.openNextRecentlyUsedEditorInGroup)`|Open Next|`workbench.action.openNextRecentlyUsedEditorInGroup` +`kb(workbench.action.openPreviousRecentlyUsedEditorInGroup)`|Open Previous|`workbench.action.openPreviousRecentlyUsedEditorInGroup` +`kb(workbench.action.files.copyPathOfActiveFile)`|Copy Path of Active File|`workbench.action.files.copyPathOfActiveFile` +`kb(workbench.action.files.revealActiveFileInWindows)`|Reveal Active File in Windows|`workbench.action.files.revealActiveFileInWindows` +`kb(workbench.action.files.showOpenedFileInNewWindow)`|Show Opened File in New Window|`workbench.action.files.showOpenedFileInNewWindow` +`kb(workbench.files.action.compareFileWith)`|Compare Opened File With|`workbench.files.action.compareFileWith` + +### Display + +Key|Command|Command id +---|-------|---------- +`kb(workbench.action.toggleFullScreen)`|Toggle Full Screen|`workbench.action.toggleFullScreen` +`kb(workbench.action.toggleZenMode)`|Toggle Zen Mode|`workbench.action.toggleZenMode` +`kb(workbench.action.exitZenMode)`|Leave Zen Mode|`workbench.action.exitZenMode` +`kb(workbench.action.zoomIn)`|Zoom in|`workbench.action.zoomIn` +`kb(workbench.action.zoomOut)`|Zoom out|`workbench.action.zoomOut` +`kb(workbench.action.zoomReset)`|Reset Zoom|`workbench.action.zoomReset` +`kb(workbench.action.toggleSidebarVisibility)`|Toggle Sidebar Visibility|`workbench.action.toggleSidebarVisibility` +`kb(workbench.view.explorer)`|Show Explorer / Toggle Focus|`workbench.view.explorer` +`kb(workbench.view.search)`|Show Search|`workbench.view.search` +`kb(workbench.view.scm)`|Show Source Control|`workbench.view.scm` +`kb(workbench.view.debug)`|Show Debug|`workbench.view.debug` +`kb(workbench.view.extensions)`|Show Extensions|`workbench.view.extensions` +`kb(workbench.action.output.toggleOutput)`|Show Output|`workbench.action.output.toggleOutput` +`kb(workbench.action.quickOpenView)`|Quick Open View|`workbench.action.quickOpenView` +`kb(workbench.action.terminal.openNativeConsole)`|Open New Command Prompt|`workbench.action.terminal.openNativeConsole` +`kb(markdown.showPreview)`|Toggle Markdown Preview|`markdown.showPreview` +`kb(markdown.showPreviewToSide)`|Open Preview to the Side|`markdown.showPreviewToSide` +`kb(workbench.action.terminal.toggleTerminal)`|Toggle Integrated Terminal|`workbench.action.terminal.toggleTerminal` + +### Search + +Key|Command|Command id +---|-------|---------- +`kb(workbench.view.search)`|Show Search|`workbench.view.search` +`kb(workbench.action.replaceInFiles)`|Replace in Files|`workbench.action.replaceInFiles` +`kb(toggleSearchCaseSensitive)`|Toggle Match Case|`toggleSearchCaseSensitive` +`kb(toggleSearchWholeWord)`|Toggle Match Whole Word|`toggleSearchWholeWord` +`kb(toggleSearchRegex)`|Toggle Use Regular Expression|`toggleSearchRegex` +`kb(workbench.action.search.toggleQueryDetails)`|Toggle Search Details|`workbench.action.search.toggleQueryDetails` +`kb(search.action.focusNextSearchResult)`|Focus Next Search Result|`search.action.focusNextSearchResult` +`kb(search.action.focusPreviousSearchResult)`|Focus Previous Search Result|`search.action.focusPreviousSearchResult` +`kb(history.showNext)`|Show Next Search Term|`history.showNext` +`kb(history.showPrevious)`|Show Previous Search Term|`history.showPrevious` + +### Preferences + +Key|Command|Command id +---|-------|---------- +`kb(workbench.action.openSettings)`|Open Settings|`workbench.action.openSettings` +`kb(workbench.action.openWorkspaceSettings)`|Open Workspace Settings|`workbench.action.openWorkspaceSettings` +`kb(workbench.action.openGlobalKeybindings)`|Open Keyboard Shortcuts|`workbench.action.openGlobalKeybindings` +`kb(workbench.action.openSnippets)`|Open User Snippets|`workbench.action.openSnippets` +`kb(workbench.action.selectTheme)`|Select Color Theme|`workbench.action.selectTheme` +`kb(workbench.action.configureLocale)`|Configure Display Language|`workbench.action.configureLocale` + +### Debug + +Key|Command|Command id +---|-------|---------- +`kb(editor.debug.action.toggleBreakpoint)`|Toggle Breakpoint|`editor.debug.action.toggleBreakpoint` +`kb(workbench.action.debug.start)`|Start|`workbench.action.debug.start` +`kb(workbench.action.debug.continue)`|Continue|`workbench.action.debug.continue` +`kb(workbench.action.debug.run)`|Start (without debugging)|`workbench.action.debug.run` +`kb(workbench.action.debug.pause)`|Pause|`workbench.action.debug.pause` +`kb(workbench.action.debug.stepInto)`|Step Into|`workbench.action.debug.stepInto` +`kb(workbench.action.debug.stepOut)`|Step Out|`workbench.action.debug.stepOut` +`kb(workbench.action.debug.stepOver)`|Step Over|`workbench.action.debug.stepOver` +`kb(workbench.action.debug.stop)`|Stop|`workbench.action.debug.stop` +`kb(editor.debug.action.showDebugHover)`|Show Hover|`editor.debug.action.showDebugHover` + +### Tasks + +Key|Command|Command id +---|-------|---------- +`kb(workbench.action.tasks.build)`|Run Build Task|`workbench.action.tasks.build` +`kb(workbench.action.tasks.test)`|Run Test Task|`workbench.action.tasks.test` + +### Extensions + +Key|Command|Command id +---|-------|---------- +`kb(workbench.extensions.action.installExtension)`|Install Extension|`workbench.extensions.action.installExtension` +`kb(workbench.extensions.action.showInstalledExtensions)`|Show Installed Extensions|`workbench.extensions.action.showInstalledExtensions` +`kb(workbench.extensions.action.listOutdatedExtensions)`|Show Outdated Extensions|`workbench.extensions.action.listOutdatedExtensions` +`kb(workbench.extensions.action.showRecommendedExtensions)`|Show Recommended Extensions|`workbench.extensions.action.showRecommendedExtensions` +`kb(workbench.extensions.action.showPopularExtensions)`|Show Popular Extensions|`workbench.extensions.action.showPopularExtensions` +`kb(workbench.extensions.action.updateAllExtensions)`|Update All Extensions|`workbench.extensions.action.updateAllExtensions` + +## Next steps + +Now that you know about our Key binding support, what's next... + +* [Language Support](/docs/languages/overview.md) - Our Good, Better, Best language grid to see what you can expect +* [Debugging](/docs/editor/debugging.md) - This is where VS Code really shines +* [Node.js](/docs/nodejs/nodejs-tutorial.md) - End to end Node.js scenario with a sample app + +## Common questions + +### How can I find out what command is bound to a specific key? + +In the **Default Keyboard Shortcuts**, open `Quick Outline` by pressing `kb(workbench.action.gotoSymbol)` + +![Key bindings quick outline](images/keybinding/outline.png) + +### How to add a key binding to an action? For example, add Ctrl+D to Delete Lines + +Find a rule that triggers the action in the **Default Keyboard Shortcuts** and write a modified version of it in your `keybindings.json` file: + +```json +// Original, in Default Keyboard Shortcuts +{ "key": "ctrl+shift+k", "command": "editor.action.deleteLines", + "when": "editorTextFocus" }, +// Modified, in User/keybindings.json, Ctrl+D now will also trigger this action +{ "key": "ctrl+d", "command": "editor.action.deleteLines", + "when": "editorTextFocus" }, +``` + +### How can I add a key binding for only certain file types? + +Use the `editorLangId` context key in your `when` clause: + +```json +{ "key": "shift+alt+a", "command": "editor.action.blockComment", + "when": "editorTextFocus && editorLangId == csharp" }, +``` + +### I have modified my key bindings in `keybindings.json`, why don't they work? + +The most common problem is a syntax error in the file. Otherwise, try removing the `when` clause or picking a different `key`. Unfortunately, at this point, it is a trial and error process. diff --git a/docs/getstarted/locales.md b/docs/getstarted/locales.md new file mode 100644 index 0000000000000000000000000000000000000000..f67eaaf90b3bef0bfabbe0bc7c64625ffa716e4a --- /dev/null +++ b/docs/getstarted/locales.md @@ -0,0 +1,92 @@ +--- +Order: 8 +Area: getstarted +TOCTitle: Display Language +PageTitle: Visual Studio Code Display Language (Locale) +ContentId: 413A7FA3-94F8-4FCB-A4A3-F4C1E77EF716 +DateApproved: 3/7/2019 +MetaDescription: How to change the display language (locale) of Visual Studio Code. +--- +# Display Language + +Visual Studio Code ships by default with English as the display language and other [languages](#available-locales) rely on Language Pack [extensions](/docs/editor/extension-gallery.md) available from the [Marketplace](https://marketplace.visualstudio.com/search?target=VSCode&category=Language%20Packs&sortBy=Downloads). + + VS Code detects the operating system's UI language and will prompt you to install the appropriate Language Pack, if available on the Marketplace. Below is an example recommending a Simplified Chinese Language Pack: + +![Language Pack recommendation](images/locales/lang-pack-recommendation.png) + +After installing the Language Pack extension and following the prompt to restart, VS Code will use the Language Pack matching your operating system's UI language. + +## Changing the Display Language + +You can also override the default UI language by explicitly setting the VS Code display language. The **Configure Display Language** command creates a `locale.json` file in your user VS Code folder where you can set the `locale` attribute to your preferred locale. + +Press `kb(workbench.action.showCommands)` to bring up the **Command Palette** then start typing "display" to filter and display the **Configure Display Language** command. + +![configure display language command ](images/locales/configure-language-command.png) + +Press `kbstyle(Enter)` and a `locale.json` file is created with the default value set to your operating system language. You can use IntelliSense (`kb(editor.action.triggerSuggest)`) to select a different supported language locale. + +![locale IntelliSense](images/locales/locale-intellisense.png) + +Save `locale.json` and restart VS Code to use the new display language. + +The example below sets VS Code to display Simplified Chinese `zh-CN`: + +```json +{ + // Defines VS Code's display language. + "locale":"zh-CN" +} +``` + +You can rerun the **Configure Display Language** command to review and change your `locale.json` file. + +>**Note:** Changing the `locale` value requires a restart of VS Code. + +## Available locales + +Display Language | Locale +-----------------|------- +English (US) | `en` +Simplified Chinese | `zh-CN` +Traditional Chinese | `zh-TW` +French | `fr` +German | `de` +Italian | `it` +Spanish | `es` +Japanese | `ja` +Korean | `ko` +Russian | `ru` +Bulgarian | `bg` +Hungarian | `hu` +Portuguese (Brazil) | `pt-br` +Turkish | `tr` + +## Marketplace Language Packs + +As described above, VS Code ships with English as the default display language, but other languages are available through [Marketplace Language Packs](https://marketplace.visualstudio.com/search?target=VSCode&category=Language%20Packs&sortBy=Downloads). + +You can search for Language Packs in the Extensions view (`kb(workbench.view.extensions)`) by typing the language you are looking for along with `category:"Language Packs"`. + +![German Language Pack](images/locales/german-language-pack.png) + +You can have multiple Language Packs installed and select the current display language with the **Configure Display Language** command. + +## Setting the Language + +If you want to use a specific language for a VS Code session, you can use the command line switch `--locale` to specify a locale when you launch VS Code. + +Below is an example of using the `--locale` command line switch to set the VS Code display language to French: + +```bash +code . --locale=fr +``` + +**Note**: You must have the appropriate Language Pack installed for the language you specify with the command line switch. If the matching Language Pack is not installed, VS Code will display English. + +## Common questions + +### Unable to write to file because the file is dirty + +This notification may mean that your `locale.json` file wasn't saved after a previous change. Make sure the file is saved and try to install the Language Pack again. \ No newline at end of file diff --git a/docs/getstarted/settings.md b/docs/getstarted/settings.md new file mode 100644 index 0000000000000000000000000000000000000000..ce921930597ca7e09400ab498cba177f64fc4de5 --- /dev/null +++ b/docs/getstarted/settings.md @@ -0,0 +1,2034 @@ +--- +Order: 6 +Area: getstarted +TOCTitle: Settings +ContentId: FDA6D86C-FF24-49BC-A1EB-E3BA43130FA0 +PageTitle: Visual Studio Code User and Workspace Settings +DateApproved: 3/7/2019 +MetaDescription: How to modify Visual Studio Code User and Workspace Settings. +--- +# User and Workspace Settings + +It is easy to configure Visual Studio Code to your liking through its various settings. Nearly every part of VS Code's editor, user interface, and functional behavior has options you can modify. + +![VS Code settings](images/settings/hero.png) + +VS Code provides two different scopes for settings: + +* **User Settings** - Settings that apply globally to any instance of VS Code you open. +* **Workspace Settings** - Settings stored inside your workspace and only apply when the workspace is opened. + +Workspace settings override user settings. + +## Creating User and Workspace Settings + +To open your user and workspace settings, use the following VS Code menu command: + +* On Windows/Linux - **File** > **Preferences** > **Settings** +* On macOS - **Code** > **Preferences** > **Settings** + +You can also open the Settings editor from the **Command Palette** (`kb(workbench.action.showCommands)`) with **Preferences: Open Settings** or use the keyboard shortcut (`kb(workbench.action.openSettings)`). + +In the example below, the color theme and the icon theme have been changed. + +![Example Settings](images/settings/settings.png) + +Changes to settings are reloaded by VS Code as you change them. Modified settings are now indicated with a _blue line_ similar to modified lines in the editor. The gear icon opens a context menu with options to reset the setting to its default value as well as copy setting as JSON. + +>**Note:** Workspace settings are useful for sharing project specific settings across a team. + +## Settings editor + +When you open the settings editor, you can search and discover settings you are looking for. When you search using the Search bar, it will not only show and highlight the settings matching your criteria, but also filter out those which are not matching. This makes finding settings quick and easy. + +![Settings Search](images/settings/settings-search.png) + +**Note**: VS Code extensions can also add their own custom settings and they will be visible under an **Extensions** section. + +### Edit settings + +Each setting can be edited by either a **checkbox**, an **input** or by a **drop-down**. Simply edit the text or select the option you want to change to the desired settings. + +![Edit a Setting](images/settings/settings-edit.png) + +### Settings groups + +Default settings are represented in groups so that you can navigate them easily. It has a **Commonly Used** group at the top which shows popular customizations. + +![Settings Groups](images/settings/settings-groups.png) + +Below is a [copy of the default settings](/docs/getstarted/settings.md#default-settings) that come with VS Code. + +## Settings file locations + +By default VS Code shows the Settings editor, but you can still edit the underlying `settings.json` file by using the **Open Settings (JSON)** command or by changing your default settings editor with the `workbench.settings.editor` setting. + +Depending on your platform, the user settings file is located here: + +* **Windows** `%APPDATA%\Code\User\settings.json` +* **macOS** `$HOME/Library/Application Support/Code/User/settings.json` +* **Linux** `$HOME/.config/Code/User/settings.json` + +The workspace setting file is located under the `.vscode` folder in your root folder. + +>**Note:** In case of a [Multi-root Workspace](/docs/editor/multi-root-workspaces.md#settings), workspace settings are located inside the workspace configuration file. + +## Language specific editor settings + +To customize your editor by language, run the global command **Preferences: Configure Language Specific Settings** (command id: `workbench.action.configureLanguageBasedSettings`) from the **Command Palette** (`kb(workbench.action.showCommands)`) which opens the language picker. Selecting the language you want, opens the Settings editor with the language entry where you can add applicable settings. + +![Configure language specific settings command](images/settings/pref-config-lang-settings.png) + +![Select language drop down](images/settings/lang-selection.png) + +![Add language specific setting](images/settings/lang-based-settings.png) + +If you have a file open and you want to customize the editor for this file type, click on the Language Mode in the Status Bar to the bottom-right of the VS Code window. This opens the Language Mode picker with an option **Configure 'language_name' language based settings**. Selecting this opens the Settings editor with the language entry where you can add applicable settings. + +You can also configure language based settings by directly opening `settings.json`. You can scope them to the workspace by placing them in the workspace settings just like other settings. If you have settings defined for a language in both user and workspace scopes, then they are merged by giving precedence to the ones defined in the workspace. + +The following examples customize editor settings for language modes `typescript` and `markdown`. + +```json +{ + "[typescript]": { + "editor.formatOnSave": true, + "editor.formatOnPaste": true + }, + "[markdown]": { + "editor.formatOnSave": true, + "editor.wordWrap": "on", + "editor.renderWhitespace": "all", + "editor.acceptSuggestionOnEnter": "off" + } +} +``` + +You can use IntelliSense in Settings editor to help you find allowed language based settings. All editor settings and some non-editor settings are supported. + +## Settings and security + +Some settings allow you to specify an executable that VS Code will run to perform certain operations. For example, you can choose which shell the Integrated Terminal should use. For enhanced security, such settings can only be defined in user settings and not at workspace scope. + +Here is the list of settings not supported in workspace settings: + +* `git.path` +* `terminal.integrated.shell.linux` +* `terminal.integrated.shellArgs.linux` +* `terminal.integrated.shell.osx` +* `terminal.integrated.shellArgs.osx` +* `terminal.integrated.shell.windows` +* `terminal.integrated.shellArgs.windows` +* `terminal.external.windowsExec` +* `terminal.external.osxExec` +* `terminal.external.linuxExec` + +The first time you open a workspace which defines any of these settings, VS Code will warn you and subsequently always ignore the values after that. + +## Default settings + +Below are the Visual Studio Code default settings and their values. You can also view the default values in the Settings editor. + +```json +{ + +// Editor + + // Controls whether the diff editor shows changes in leading or trailing whitespace as diffs. + "diffEditor.ignoreTrimWhitespace": true, + + // Controls whether the diff editor shows +/- indicators for added/removed changes. + "diffEditor.renderIndicators": true, + + // Controls whether the diff editor shows the diff side by side or inline. + "diffEditor.renderSideBySide": true, + + // Controls whether suggestions should be accepted on commit characters. For example, in JavaScript, the semi-colon (`;`) can be a commit character that accepts a suggestion and types that character. + "editor.acceptSuggestionOnCommitCharacter": true, + + // Controls whether suggestions should be accepted on `Enter`, in addition to `Tab`. Helps to avoid ambiguity between inserting new lines or accepting suggestions. + // - on + // - smart: Only accept a suggestion with `Enter` when it makes a textual change. + // - off + "editor.acceptSuggestionOnEnter": "on", + + // Controls whether the editor should run in a mode where it is optimized for screen readers. + // - auto: The editor will use platform APIs to detect when a Screen Reader is attached. + // - on: The editor will be permanently optimized for usage with a Screen Reader. + // - off: The editor will never be optimized for usage with a Screen Reader. + "editor.accessibilitySupport": "auto", + + // Controls whether the editor should automatically close brackets after the user adds an opening bracket. + // - always + // - languageDefined: Use language configurations to determine when to autoclose brackets. + // - beforeWhitespace: Autoclose brackets only when the cursor is to the left of whitespace. + // - never + "editor.autoClosingBrackets": "languageDefined", + + // Controls whether the editor should automatically close quotes after the user adds an opening quote. + // - always + // - languageDefined: Use language configurations to determine when to autoclose quotes. + // - beforeWhitespace: Autoclose quotes only when the cursor is to the left of whitespace. + // - never + "editor.autoClosingQuotes": "languageDefined", + + // Controls whether the editor should automatically adjust the indentation when users type, paste or move lines. Extensions with indentation rules of the language must be available. + "editor.autoIndent": true, + + // Controls whether the editor should automatically surround selections. + // - languageDefined: Use language configurations to determine when to automatically surround selections. + // - brackets: Surround with brackets but not quotes. + // - quotes: Surround with quotes but not brackets. + // - never + "editor.autoSurround": "languageDefined", + + // Code action kinds to be run on save. + "editor.codeActionsOnSave": {}, + + // Timeout in milliseconds after which the code actions that are run on save are cancelled. + "editor.codeActionsOnSaveTimeout": 750, + + // Controls whether the editor shows CodeLens. + "editor.codeLens": true, + + // Controls whether the editor should render the inline color decorators and color picker. + "editor.colorDecorators": true, + + // Controls whether syntax highlighting should be copied into the clipboard. + "editor.copyWithSyntaxHighlighting": true, + + // Control the cursor animation style. + "editor.cursorBlinking": "blink", + + // Controls whether the smooth caret animation should be enabled. + "editor.cursorSmoothCaretAnimation": false, + + // Controls the cursor style. + "editor.cursorStyle": "line", + + // Controls the width of the cursor when `editor.cursorStyle` is set to `line`. + "editor.cursorWidth": 0, + + // Controls whether `editor.tabSize#` and `#editor.insertSpaces` will be automatically detected when a file is opened based on the file contents. + "editor.detectIndentation": true, + + // Controls whether the editor should allow moving selections via drag and drop. + "editor.dragAndDrop": true, + + // Controls whether copying without a selection copies the current line. + "editor.emptySelectionClipboard": true, + + // Scrolling speed mulitiplier when pressing `Alt`. + "editor.fastScrollSensitivity": 5, + + // Controls whether the Find Widget should add extra lines on top of the editor. When true, you can scroll beyond the first line when the Find Widget is visible. + "editor.find.addExtraSpaceOnTop": true, + + // Controls whether the find operation is carried out on selected text or the entire file in the editor. + "editor.find.autoFindInSelection": false, + + // Controls whether the Find Widget should read or modify the shared find clipboard on macOS. + "editor.find.globalFindClipboard": true, + + // Controls whether the search string in the Find Widget is seeded from the editor selection. + "editor.find.seedSearchStringFromSelection": true, + + // Controls whether the editor has code folding enabled. + "editor.folding": true, + + // Controls the strategy for computing folding ranges. `auto` uses a language specific folding strategy, if available. `indentation` uses the indentation based folding strategy. + "editor.foldingStrategy": "auto", + + // Controls the font family. + "editor.fontFamily": "Consolas, 'Courier New', monospace", + + // Enables/Disables font ligatures. + "editor.fontLigatures": false, + + // Controls the font size in pixels. + "editor.fontSize": 14, + + // Controls the font weight. + "editor.fontWeight": "normal", + + // Controls whether the editor should automatically format the pasted content. A formatter must be available and the formatter should be able to format a range in a document. + "editor.formatOnPaste": false, + + // Format a file on save. A formatter must be available, the file must not be saved after delay, and the editor must not be shutting down. + "editor.formatOnSave": false, + + // Timeout in milliseconds after which the formatting that is run on file save is cancelled. + "editor.formatOnSaveTimeout": 750, + + // Controls whether the editor should automatically format the line after typing. + "editor.formatOnType": false, + + // Controls whether the editor should render the vertical glyph margin. Glyph margin is mostly used for debugging. + "editor.glyphMargin": true, + + // Controls whether the cursor should be hidden in the overview ruler. + "editor.hideCursorInOverviewRuler": false, + + // Controls whether the editor should highlight the active indent guide. + "editor.highlightActiveIndentGuide": true, + + // Controls the delay in milliseconds after which the hover is shown. + "editor.hover.delay": 300, + + // Controls whether the hover is shown. + "editor.hover.enabled": true, + + // Controls whether the hover should remain visible when mouse is moved over it. + "editor.hover.sticky": true, + + // Insert spaces when pressing `Tab`. This setting is overridden based on the file contents when `editor.detectIndentation` is on. + "editor.insertSpaces": true, + + // Controls the letter spacing in pixels. + "editor.letterSpacing": 0, + + // Enables the code action lightbulb in the editor. + "editor.lightbulb.enabled": true, + + // Controls the line height. Use 0 to compute the line height from the font size. + "editor.lineHeight": 0, + + // Controls the display of line numbers. + // - off: Line numbers are not rendered. + // - on: Line numbers are rendered as absolute number. + // - relative: Line numbers are rendered as distance in lines to cursor position. + // - interval: Line numbers are rendered every 10 lines. + "editor.lineNumbers": "on", + + // Controls whether the editor should detect links and make them clickable. + "editor.links": true, + + // Highlight matching brackets when one of them is selected. + "editor.matchBrackets": true, + + // Controls whether the minimap is shown. + "editor.minimap.enabled": true, + + // Limit the width of the minimap to render at most a certain number of columns. + "editor.minimap.maxColumn": 120, + + // Render the actual characters on a line as opposed to color blocks. + "editor.minimap.renderCharacters": true, + + // Controls whether the minimap slider is automatically hidden. + "editor.minimap.showSlider": "mouseover", + + // Controls the side where to render the minimap. + "editor.minimap.side": "right", + + // A multiplier to be used on the `deltaX` and `deltaY` of mouse wheel scroll events. + "editor.mouseWheelScrollSensitivity": 1, + + // Zoom the font of the editor when using mouse wheel and holding `Ctrl`. + "editor.mouseWheelZoom": false, + + // The modifier to be used to add multiple cursors with the mouse. The Go To Definition and Open Link mouse gestures will adapt such that they do not conflict with the multicursor modifier. [Read more](https://code.visualstudio.com/docs/editor/codebasics#_multicursor-modifier). + // - ctrlCmd: Maps to `Control` on Windows and Linux and to `Command` on macOS. + // - alt: Maps to `Alt` on Windows and Linux and to `Option` on macOS. + "editor.multiCursorModifier": "alt", + + // Controls whether the editor should highlight semantic symbol occurrences. + "editor.occurrencesHighlight": true, + + // Controls whether a border should be drawn around the overview ruler. + "editor.overviewRulerBorder": true, + + // Controls the number of decorations that can show up at the same position in the overview ruler. + "editor.overviewRulerLanes": 3, + + // Controls whether the parameter hints menu cycles or closes when reaching the end of the list. + "editor.parameterHints.cycle": false, + + // Enables a pop-up that shows parameter documentation and type information as you type. + "editor.parameterHints.enabled": true, + + // Controls whether suggestions should automatically show up while typing. + "editor.quickSuggestions": { + "other": true, + "comments": false, + "strings": false + }, + + // Controls the delay in milliseconds after which quick suggestions will show up. + "editor.quickSuggestionsDelay": 10, + + // Controls whether the editor should render control characters. + "editor.renderControlCharacters": false, + + // Render last line number when the file ends with a newline. + "editor.renderFinalNewline": true, + + // Controls whether the editor should render indent guides. + "editor.renderIndentGuides": true, + + // Controls how the editor should render the current line highlight. + // - none + // - gutter + // - line + // - all: Highlights both the gutter and the current line. + "editor.renderLineHighlight": "line", + + // Controls how the editor should render whitespace characters. + // - none + // - boundary: Render whitespace characters except for single spaces between words. + // - all + "editor.renderWhitespace": "none", + + // Controls whether selections should have rounded corners. + "editor.roundedSelection": true, + + // Render vertical rulers after a certain number of monospace characters. Use multiple values for multiple rulers. No rulers are drawn if array is empty. + "editor.rulers": [], + + // Controls the number of extra characters beyond which the editor will scroll horizontally. + "editor.scrollBeyondLastColumn": 5, + + // Controls whether the editor will scroll beyond the last line. + "editor.scrollBeyondLastLine": true, + + // Controls whether the Linux primary clipboard should be supported. + "editor.selectionClipboard": true, + + // Controls whether the editor should highlight matches similar to the selection. + "editor.selectionHighlight": true, + + // Controls whether the fold controls on the gutter are automatically hidden. + "editor.showFoldingControls": "mouseover", + + // Controls fading out of unused code. + "editor.showUnused": true, + + // Controls whether the editor will scroll using an animation. + "editor.smoothScrolling": false, + + // Controls whether snippets are shown with other suggestions and how they are sorted. + // - top: Show snippet suggestions on top of other suggestions. + // - bottom: Show snippet suggestions below other suggestions. + // - inline: Show snippets suggestions with other suggestions. + // - none: Do not show snippet suggestions. + "editor.snippetSuggestions": "inline", + + // Keep peek editors open even when double clicking their content or when hitting `Escape`. + "editor.stablePeek": false, + + // Controls whether filtering and sorting suggestions accounts for small typos. + "editor.suggest.filterGraceful": true, + + // Controls whether sorting favours words that appear close to the cursor. + "editor.suggest.localityBonus": false, + + // Controls whether remembered suggestion selections are shared between multiple workspaces and windows (needs `editor.suggestSelection`). + "editor.suggest.shareSuggestSelections": false, + + // Control whether an active snippet prevents quick suggestions. + "editor.suggest.snippetsPreventQuickSuggestions": true, + + // Font size for the suggest widget. When set to `0`, the value of `editor.fontSize` is used. + "editor.suggestFontSize": 0, + + // Line height for the suggest widget. When set to `0`, the value of `editor.lineHeight` is used. + "editor.suggestLineHeight": 0, + + // Controls whether suggestions should automatically show up when typing trigger characters. + "editor.suggestOnTriggerCharacters": true, + + // Controls how suggestions are pre-selected when showing the suggest list. + // - first: Always select the first suggestion. + // - recentlyUsed: Select recent suggestions unless further typing selects one, e.g. `console.| -> console.log` because `log` has been completed recently. + // - recentlyUsedByPrefix: Select suggestions based on previous prefixes that have completed those suggestions, e.g. `co -> console` and `con -> const`. + "editor.suggestSelection": "recentlyUsed", + + // Enables tab completions. + // - on: Tab complete will insert the best matching suggestion when pressing tab. + // - off: Disable tab completions. + // - onlySnippets: Tab complete snippets when their prefix match. Works best when 'quickSuggestions' aren't enabled. + "editor.tabCompletion": "off", + + // The number of spaces a tab is equal to. This setting is overridden based on the file contents when `editor.detectIndentation` is on. + "editor.tabSize": 4, + + // Overrides editor colors and font style from the currently selected color theme. + "editor.tokenColorCustomizations": {}, + + // Remove trailing auto inserted whitespace. + "editor.trimAutoWhitespace": true, + + // Inserting and deleting whitespace follows tab stops. + "editor.useTabStops": true, + + // Controls whether completions should be computed based on words in the document. + "editor.wordBasedSuggestions": true, + + // Characters that will be used as word separators when doing word related navigations or operations. + "editor.wordSeparators": "`~!@#$%^&*()-=+[{]}\\|;:'\",.<>/?", + + // Controls how lines should wrap. + // - off: Lines will never wrap. + // - on: Lines will wrap at the viewport width. + // - wordWrapColumn: Lines will wrap at `editor.wordWrapColumn`. + // - bounded: Lines will wrap at the minimum of viewport and `editor.wordWrapColumn`. + "editor.wordWrap": "off", + + // Controls the wrapping column of the editor when `editor.wordWrap` is `wordWrapColumn` or `bounded`. + "editor.wordWrapColumn": 80, + + // Controls the indentation of wrapped lines. + // - none: No indentation. Wrapped lines begin at column 1. + // - same: Wrapped lines get the same indentation as the parent. + // - indent: Wrapped lines get +1 indentation toward the parent. + // - deepIndent: Wrapped lines get +2 indentation toward the parent. + "editor.wrappingIndent": "same", + +// SCM + + // Controls whether inline actions are always visible in the Source Control view. + "scm.alwaysShowActions": false, + + // Controls whether to always show the Source Control Provider section. + "scm.alwaysShowProviders": false, + + // Controls diff decorations in the editor. + "scm.diffDecorations": "all", + + // Controls the width(px) of diff decorations in gutter (added & modified). + "scm.diffDecorationsGutterWidth": 3, + +// Workbench + + // Controls the visibility of the activity bar in the workbench. + "workbench.activityBar.visible": true, + + // Overrides colors from the currently selected color theme. + "workbench.colorCustomizations": {}, + + // Specifies the color theme used in the workbench. + "workbench.colorTheme": "Default Dark+", + + // Controls the number of recently used commands to keep in history for the command palette. Set to 0 to disable command history. + "workbench.commandPalette.history": 50, + + // Controls whether the last typed input to the command palette should be restored when opening it the next time. + "workbench.commandPalette.preserveInput": false, + + // Controls if the centered layout should automatically resize to maximum width when more than one group is open. Once only one group is open it will resize back to the original centered width. + "workbench.editor.centeredLayoutAutoResize": true, + + // Controls the behavior of empty editor groups when the last tab in the group is closed. When enabled, empty groups will automatically close. When disabled, empty groups will remain part of the grid. + "workbench.editor.closeEmptyGroups": true, + + // Controls whether editors showing a file that was opened during the session should close automatically when getting deleted or renamed by some other process. Disabling this will keep the editor open on such an event. Note that deleting from within the application will always close the editor and that dirty files will never close to preserve your data. + "workbench.editor.closeOnFileDelete": false, + + // Controls whether opened editors show as preview. Preview editors are reused until they are pinned (e.g. via double click or editing) and show up with an italic font style. + "workbench.editor.enablePreview": true, + + // Controls whether opened editors from Quick Open show as preview. Preview editors are reused until they are pinned (e.g. via double click or editing). + "workbench.editor.enablePreviewFromQuickOpen": true, + + // Controls whether tabs are closed in most recently used order or from left to right. + "workbench.editor.focusRecentEditorAfterClose": true, + + // Controls whether a top border is drawn on modified (dirty) editor tabs or not. + "workbench.editor.highlightModifiedTabs": false, + + // Controls the format of the label for an editor. + // - default: Show the name of the file. When tabs are enabled and two files have the same name in one group the distinguishing sections of each file's path are added. When tabs are disabled, the path relative to the workspace folder is shown if the editor is active. + // - short: Show the name of the file followed by its directory name. + // - medium: Show the name of the file followed by its path relative to the workspace folder. + // - long: Show the name of the file followed by its absolute path. + "workbench.editor.labelFormat": "default", + + // Controls where editors open. Select `left` or `right` to open editors to the left or right of the currently active one. Select `first` or `last` to open editors independently from the currently active one. + "workbench.editor.openPositioning": "right", + + // Controls the default direction of editors that are opened side by side (e.g. from the explorer). By default, editors will open on the right hand side of the currently active one. If changed to `down`, the editors will open below the currently active one. + "workbench.editor.openSideBySideDirection": "right", + + // Restores the last view state (e.g. scroll position) when re-opening files after they have been closed. + "workbench.editor.restoreViewState": true, + + // Controls whether an editor is revealed in any of the visible groups if opened. If disabled, an editor will prefer to open in the currently active editor group. If enabled, an already opened editor will be revealed instead of opened again in the currently active editor group. Note that there are some cases where this setting is ignored, e.g. when forcing an editor to open in a specific group or to the side of the currently active group. + "workbench.editor.revealIfOpen": false, + + // Controls whether opened editors should show with an icon or not. This requires an icon theme to be enabled as well. + "workbench.editor.showIcons": true, + + // Controls whether opened editors should show in tabs or not. + "workbench.editor.showTabs": true, + + // Navigate between open files using three-finger swipe horizontally. + "workbench.editor.swipeToNavigate": false, + + // Controls the position of the editor's tabs close buttons, or disables them when set to 'off'. + "workbench.editor.tabCloseButton": "right", + + // Controls the sizing of editor tabs. + // - fit: Always keep tabs large enough to show the full editor label. + // - shrink: Allow tabs to get smaller when the available space is not enough to show all tabs at once. + "workbench.editor.tabSizing": "fit", + + // Controls font aliasing method in the workbench. + // - default: Sub-pixel font smoothing. On most non-retina displays this will give the sharpest text. + // - antialiased: Smooth the font on the level of the pixel, as opposed to the subpixel. Can make the font appear lighter overall. + // - none: Disables font smoothing. Text will show with jagged sharp edges. + // - auto: Applies `default` or `antialiased` automatically based on the DPI of displays. + "workbench.fontAliasing": "default", + + // Specifies the icon theme used in the workbench or 'null' to not show any file icons. + // - null: No file icons + // - vs-minimal + // - vs-seti + "workbench.iconTheme": "vs-seti", + + // Controls whether keyboard navigation in lists and trees is automatically triggered simply by typing. If set to `false`, keyboard navigation is only triggered when executing the `list.toggleKeyboardNavigation` command, for which you can assign a keyboard shortcut. + "workbench.list.automaticKeyboardNavigation": true, + + // Controls whether lists and trees support horizontal scrolling in the workbench. + "workbench.list.horizontalScrolling": false, + + // Controls the keyboard navigation style for lists and trees in the workbench. Can be simple, highlight and filter. + // - simple: Simple keyboard navigation focuses elements which match the keyboard input. Matching is done only on prefixes. + // - highlight: Highlight keyboard navigation highlights elements which match the keyboard input. Further up and down navigation will traverse only the highlighted elements. + // - filter: Filter keyboard navigation will filter out and hide all the elements which do not match the keyboard input. + "workbench.list.keyboardNavigation": "highlight", + + // The modifier to be used to add an item in trees and lists to a multi-selection with the mouse (for example in the explorer, open editors and scm view). The 'Open to Side' mouse gestures - if supported - will adapt such that they do not conflict with the multiselect modifier. + // - ctrlCmd: Maps to `Control` on Windows and Linux and to `Command` on macOS. + // - alt: Maps to `Alt` on Windows and Linux and to `Option` on macOS. + "workbench.list.multiSelectModifier": "ctrlCmd", + + // Controls how to open items in trees and lists using the mouse (if supported). For parents with children in trees, this setting will control if a single click expands the parent or a double click. Note that some trees and lists might choose to ignore this setting if it is not applicable. + "workbench.list.openMode": "singleClick", + + // Controls the default location of the panel (terminal, debug console, output, problems). It can either show at the bottom or on the right of the workbench. + "workbench.panel.defaultLocation": "bottom", + + // Controls whether Quick Open should close automatically once it loses focus. + "workbench.quickOpen.closeOnFocusLost": true, + + // Controls whether the last typed input to Quick Open should be restored when opening it the next time. + "workbench.quickOpen.preserveInput": false, + + // Determines which settings editor to use by default. + // - ui: Use the settings UI editor. + // - json: Use the JSON file editor. + "workbench.settings.editor": "ui", + + // Controls whether to enable the natural language search mode for settings. The natural language search is provided by a Microsoft online service. + "workbench.settings.enableNaturalLanguageSearch": true, + + // Controls whether opening keybinding settings also opens an editor showing all default keybindings. + "workbench.settings.openDefaultKeybindings": false, + + // Controls whether opening settings also opens an editor showing all default settings. + "workbench.settings.openDefaultSettings": false, + + // Controls the behavior of the settings editor Table of Contents while searching. + // - hide: Hide the Table of Contents while searching. + // - filter: Filter the Table of Contents to just categories that have matching settings. Clicking a category will filter the results to that category. + "workbench.settings.settingsSearchTocBehavior": "filter", + + // Controls whether to use the split JSON editor when editing settings as JSON. + "workbench.settings.useSplitJSON": false, + + // Controls the location of the sidebar. It can either show on the left or right of the workbench. + "workbench.sideBar.location": "left", + + // Controls which editor is shown at startup, if none are restored from the previous session. + // - none: Start without an editor. + // - welcomePage: Open the Welcome page (default). + // - readme: Open the README when opening a folder that contains one, fallback to 'welcomePage' otherwise. + // - newUntitledFile: Open a new untitled file (only applies when opening an empty workspace). + // - welcomePageInEmptyWorkbench: Open the Welcome page when opening an empty workbench. + "workbench.startupEditor": "welcomePage", + + // Controls the visibility of the Twitter feedback (smiley) in the status bar at the bottom of the workbench. + "workbench.statusBar.feedback.visible": true, + + // Controls the visibility of the status bar at the bottom of the workbench. + "workbench.statusBar.visible": true, + + // When enabled, will show the watermark tips when no editor is open. + "workbench.tips.enabled": true, + + // Controls tree indentation in pixels. + "workbench.tree.indent": 8, + + // Controls the visibility of view header actions. View header actions may either be always visible, or only visible when that view is focused or hovered over. + "workbench.view.alwaysShowHeaderActions": false, + +// Window + + // If enabled, will automatically change to high contrast theme if Windows is using a high contrast theme, and to dark theme when switching away from a Windows high contrast theme. + "window.autoDetectHighContrast": true, + + // If enabled, clicking on an inactive window will both activate the window and trigger the element under the mouse if it is clickable. If disabled, clicking anywhere on an inactive window will activate it only and a second click is required on the element. + "window.clickThroughInactive": true, + + // Controls whether closing the last editor should also close the window. This setting only applies for windows that do not show folders. + "window.closeWhenEmpty": false, + + // If enabled, double clicking the application icon in the title bar will close the window and the window cannot be dragged by the icon. This setting only has an effect when `window.titleBarStyle` is set to `custom`. + "window.doubleClickIconToClose": false, + + // Enables macOS Sierra window tabs. Note that changes require a full restart to apply and that native tabs will disable a custom title bar style if configured. + "window.nativeTabs": false, + + // If enabled, the main menus can be opened via Alt-key shortcuts. Disabling mnemonics allows to bind these Alt-key shortcuts to editor commands instead. + "window.enableMenuBarMnemonics": true, + + // Control the visibility of the menu bar. A setting of 'toggle' means that the menu bar is hidden and a single press of the Alt key will show it. By default, the menu bar will be visible, unless the window is full screen. + // - default: Menu is only hidden in full screen mode. + // - visible: Menu is always visible even in full screen mode. + // - toggle: Menu is hidden but can be displayed via Alt key. + // - hidden: Menu is always hidden. + "window.menuBarVisibility": "default", + + // Controls the dimensions of opening a new window when at least one window is already opened. Note that this setting does not have an impact on the first window that is opened. The first window will always restore the size and location as you left it before closing. + // - default: Open new windows in the center of the screen. + // - inherit: Open new windows with same dimension as last active one. + // - maximized: Open new windows maximized. + // - fullscreen: Open new windows in full screen mode. + "window.newWindowDimensions": "default", + + // Controls whether files should open in a new window. + // Note that there can still be cases where this setting is ignored (e.g. when using the `--new-window` or `--reuse-window` command line option). + // - on: Files will open in a new window. + // - off: Files will open in the window with the files' folder open or the last active window. + // - default: Files will open in a new window unless picked from within the application (e.g. via the File menu). + "window.openFilesInNewWindow": "off", + + // Controls whether folders should open in a new window or replace the last active window. + // Note that there can still be cases where this setting is ignored (e.g. when using the `--new-window` or `--reuse-window` command line option). + // - on: Folders will open in a new window. + // - off: Folders will replace the last active window. + // - default: Folders will open in a new window unless a folder is picked from within the application (e.g. via the File menu). + "window.openFoldersInNewWindow": "default", + + // Controls whether a new empty window should open when starting a second instance without arguments or if the last running instance should get focus. + // Note that there can still be cases where this setting is ignored (e.g. when using the `--new-window` or `--reuse-window` command line option). + // - on: Open a new empty window. + // - off: Focus the last active running instance. + "window.openWithoutArgumentsInNewWindow": "on", + + // Controls whether a window should restore to full screen mode if it was exited in full screen mode. + "window.restoreFullscreen": false, + + // Controls how windows are being reopened after a restart. + // - all: Reopen all windows. + // - folders: Reopen all folders. Empty workspaces will not be restored. + // - one: Reopen the last active window. + // - none: Never reopen a window. Always start with an empty one. + "window.restoreWindows": "one", + + // Controls the window title based on the active editor. Variables are substituted based on the context: + // - `${activeEditorShort}`: the file name (e.g. myFile.txt). + // - `${activeEditorMedium}`: the path of the file relative to the workspace folder (e.g. myFolder/myFileFolder/myFile.txt). + // - `${activeEditorLong}`: the full path of the file (e.g. /Users/Development/myFolder/myFileFolder/myFile.txt). + // - `${activeFolderShort}`: the name of the folder the file is contained in (e.g. myFileFolder). + // - `${activeFolderMedium}`: the path of the folder the file is contained in, relative to the workspace folder (e.g. myFolder/myFileFolder). + // - `${activeFolderLong}`: the full path of the folder the file is contained in (e.g. /Users/Development/myFolder/myFileFolder). + // - `${folderName}`: name of the workspace folder the file is contained in (e.g. myFolder). + // - `${folderPath}`: file path of the workspace folder the file is contained in (e.g. /Users/Development/myFolder). + // - `${rootName}`: name of the workspace (e.g. myFolder or myWorkspace). + // - `${rootPath}`: file path of the workspace (e.g. /Users/Development/myWorkspace). + // - `${appName}`: e.g. VS Code. + // - `${dirty}`: a dirty indicator if the active editor is dirty. + // - `${separator}`: a conditional separator (" - ") that only shows when surrounded by variables with values or static text. + "window.title": "${dirty}${activeEditorShort}${separator}${rootName}${separator}${appName}", + + // Adjust the appearance of the window title bar. On Linux and Windows, this setting also affects the application and context menu appearances. Changes require a full restart to apply. + "window.titleBarStyle": "custom", + + // Adjust the zoom level of the window. The original size is 0 and each increment above (e.g. 1) or below (e.g. -1) represents zooming 20% larger or smaller. You can also enter decimals to adjust the zoom level with a finer granularity. + "window.zoomLevel": 0, + +// Files + + // Configure file associations to languages (e.g. `"*.extension": "html"`). These have precedence over the default associations of the languages installed. + "files.associations": {}, + + // When enabled, the editor will attempt to guess the character set encoding when opening files. This setting can also be configured per language. + "files.autoGuessEncoding": false, + + // Controls auto save of dirty files. Read more about autosave [here](https://code.visualstudio.com/docs/editor/codebasics#_save-auto-save). + // - off: A dirty file is never automatically saved. + // - afterDelay: A dirty file is automatically saved after the configured `files.autoSaveDelay`. + // - onFocusChange: A dirty file is automatically saved when the editor loses focus. + // - onWindowChange: A dirty file is automatically saved when the window loses focus. + "files.autoSave": "off", + + // Controls the delay in ms after which a dirty file is saved automatically. Only applies when `files.autoSave` is set to `afterDelay`. + "files.autoSaveDelay": 1000, + + // The default language mode that is assigned to new files. + "files.defaultLanguage": "", + + // Moves files/folders to the OS trash (recycle bin on Windows) when deleting. Disabling this will delete files/folders permanently. + "files.enableTrash": true, + + // The default character set encoding to use when reading and writing files. This setting can also be configured per language. + "files.encoding": "utf8", + + // The default end of line character. + // - \n: LF + // - \r\n: CRLF + // - auto: Uses operating system specific end of line character. + "files.eol": "auto", + + // Configure glob patterns for excluding files and folders. For example, the files explorer decides which files and folders to show or hide based on this setting. Read more about glob patterns [here](https://code.visualstudio.com/docs/editor/codebasics#_advanced-search-options). + "files.exclude": { + "**/.git": true, + "**/.svn": true, + "**/.hg": true, + "**/CVS": true, + "**/.DS_Store": true + }, + + // Controls whether unsaved files are remembered between sessions, allowing the save prompt when exiting the editor to be skipped. + // - off: Disable hot exit. + // - onExit: Hot exit will be triggered when the last window is closed on Windows/Linux or when the `workbench.action.quit` command is triggered (command palette, keybinding, menu). All windows with backups will be restored upon next launch. + // - onExitAndWindowClose: Hot exit will be triggered when the last window is closed on Windows/Linux or when the `workbench.action.quit` command is triggered (command palette, keybinding, menu), and also for any window with a folder opened regardless of whether it's the last window. All windows without folders opened will be restored upon next launch. To restore folder windows as they were before shutdown set `window.restoreWindows` to `all`. + "files.hotExit": "onExit", + + // When enabled, insert a final new line at the end of the file when saving it. + "files.insertFinalNewline": false, + + // Controls the memory available to VS Code after restart when trying to open large files. Same effect as specifying `--max-memory=NEWSIZE` on the command line. + "files.maxMemoryForLargeFilesMB": 4096, + + // When enabled, will trim all new lines after the final new line at the end of the file when saving it. + "files.trimFinalNewlines": false, + + // When enabled, will trim trailing whitespace when saving a file. + "files.trimTrailingWhitespace": false, + + // Configure glob patterns of file paths to exclude from file watching. Patterns must match on absolute paths (i.e. prefix with ** or the full path to match properly). Changing this setting requires a restart. When you experience Code consuming lots of cpu time on startup, you can exclude large folders to reduce the initial load. + "files.watcherExclude": { + "**/.git/objects/**": true, + "**/.git/subtree-cache/**": true, + "**/node_modules/*/**": true + }, + +// Zen Mode + + // Controls whether turning on Zen Mode also centers the layout. + "zenMode.centerLayout": true, + + // Controls whether turning on Zen Mode also puts the workbench into full screen mode. + "zenMode.fullScreen": true, + + // Controls whether turning on Zen Mode also hides the activity bar at the left of the workbench. + "zenMode.hideActivityBar": true, + + // Controls whether turning on Zen Mode also hides the editor line numbers. + "zenMode.hideLineNumbers": true, + + // Controls whether turning on Zen Mode also hides the status bar at the bottom of the workbench. + "zenMode.hideStatusBar": true, + + // Controls whether turning on Zen Mode also hides workbench tabs. + "zenMode.hideTabs": true, + + // Controls whether a window should restore to zen mode if it was exited in zen mode. + "zenMode.restore": false, + +// File Explorer + + // Controls whether the explorer should automatically reveal and select files when opening them. + "explorer.autoReveal": true, + + // Controls whether the explorer should ask for confirmation when deleting a file via the trash. + "explorer.confirmDelete": true, + + // Controls whether the explorer should ask for confirmation to move files and folders via drag and drop. + "explorer.confirmDragAndDrop": true, + + // Controls whether file decorations should use badges. + "explorer.decorations.badges": true, + + // Controls whether file decorations should use colors. + "explorer.decorations.colors": true, + + // Controls whether the explorer should allow to move files and folders via drag and drop. + "explorer.enableDragAndDrop": true, + + // Number of editors shown in the Open Editors pane. + "explorer.openEditors.visible": 9, + + // Controls sorting order of files and folders in the explorer. + // - default: Files and folders are sorted by their names, in alphabetical order. Folders are displayed before files. + // - mixed: Files and folders are sorted by their names, in alphabetical order. Files are interwoven with folders. + // - filesFirst: Files and folders are sorted by their names, in alphabetical order. Files are displayed before folders. + // - type: Files and folders are sorted by their extensions, in alphabetical order. Folders are displayed before files. + // - modified: Files and folders are sorted by last modified date, in descending order. Folders are displayed before files. + "explorer.sortOrder": "default", + +// Search + + // Controls the positioning of the actionbar on rows in the search view. + // - auto: Position the actionbar to the right when the search view is narrow, and immediately after the content when the search view is wide. + // - right: Always position the actionbar to the right. + "search.actionsPosition": "auto", + + // Controls whether the search results will be collapsed or expanded. + // - auto: Files with less than 10 results are expanded. Others are collapsed. + // - alwaysCollapse + // - alwaysExpand + "search.collapseResults": "auto", + + // Configure glob patterns for excluding files and folders in searches. Inherits all glob patterns from the `files.exclude` setting. Read more about glob patterns [here](https://code.visualstudio.com/docs/editor/codebasics#_advanced-search-options). + "search.exclude": { + "**/node_modules": true, + "**/bower_components": true + }, + + // Controls whether to follow symlinks while searching. + "search.followSymlinks": true, + + // Controls whether the search view should read or modify the shared find clipboard on macOS. + "search.globalFindClipboard": false, + + // Controls whether the search will be shown as a view in the sidebar or as a panel in the panel area for more horizontal space. + "search.location": "sidebar", + + // Whether to include results from recently opened files in the file results for Quick Open. + "search.quickOpen.includeHistory": true, + + // Whether to include results from a global symbol search in the file results for Quick Open. + "search.quickOpen.includeSymbols": false, + + // Controls whether to show line numbers for search results. + "search.showLineNumbers": false, + + // Search case-insensitively if the pattern is all lowercase, otherwise, search case-sensitively. + "search.smartCase": false, + + // Controls whether to use global `.gitignore` and `.ignore` files when searching for files. + "search.useGlobalIgnoreFiles": false, + + // Controls whether to use `.gitignore` and `.ignore` files when searching for files. + "search.useIgnoreFiles": true, + + // Whether to use the PCRE2 regex engine in text search. This enables using some advanced regex features like lookahead and backreferences. However, not all PCRE2 features are supported - only features that are also supported by JavaScript. + "search.usePCRE2": false, + + // Controls whether to open Replace Preview when selecting or replacing a match. + "search.useReplacePreview": true, + +// HTTP + + // The proxy setting to use. If not set will be taken from the http_proxy and https_proxy environment variables. + "http.proxy": "", + + // The value to send as the 'Proxy-Authorization' header for every network request. + "http.proxyAuthorization": null, + + // Controls whether the proxy server certificate should be verified against the list of supplied CAs. + "http.proxyStrictSSL": true, + + // Use the proxy support for extensions. + // - off: Disable proxy support for extensions. + // - on: Enable proxy support for extensions. + // - override: Enable proxy support for extensions, override request options. + "http.proxySupport": "override", + +// Keyboard + + // Controls the dispatching logic for key presses to use either `code` (recommended) or `keyCode`. + "keyboard.dispatch": "code", + + // Enables the macOS touchbar buttons on the keyboard if available. + "keyboard.touchbar.enabled": true, + +// Update + + // Enables Windows background updates. The updates are fetched from a Microsoft online service. + "update.enableWindowsBackgroundUpdates": true, + + // Configure whether you receive automatic updates. Requires a restart after change. The updates are fetched from a Microsoft online service. + // - none: Disable updates. + // - manual: Disable automatic background update checks. Updates will be available if you manually check for updates. + // - default: Enable automatic update checks. Code will check for updates automatically and periodically. + "update.mode": "default", + + // Show Release Notes after an update. The Release Notes are fetched from a Microsoft online service. + "update.showReleaseNotes": true, + +// Debug + + // Allow setting breakpoints in any file. + "debug.allowBreakpointsEverywhere": false, + + // Controls the font family in the debug console. + "debug.console.fontFamily": "default", + + // Controls the font size in pixels in the debug console. + "debug.console.fontSize": 14, + + // Controls the line height in pixels in the debug console. Use 0 to compute the line height from the font size. + "debug.console.lineHeight": 0, + + // Controls whether the non-debug hovers should be enabled while debugging. When enabled the hover providers will be called to provide a hover. Regular hovers will not be shown even if this setting is enabled. + "debug.enableAllHovers": false, + + // Show variable values inline in editor while debugging. + "debug.inlineValues": false, + + // Controls when the internal debug console should open. + "debug.internalConsoleOptions": "openOnFirstSessionStart", + + // Controls when the debug view should open. + "debug.openDebug": "openOnSessionStart", + + // Automatically open the explorer view at the end of a debug session. + "debug.openExplorerOnEnd": false, + + // Controls when the debug status bar should be visible. + // - never: Never show debug in status bar + // - always: Always show debug in status bar + // - onFirstSessionStart: Show debug in status bar only after debug was started for the first time + "debug.showInStatusBar": "onFirstSessionStart", + + // Controls the location of the debug toolbar. Either `floating` in all views, `docked` in the debug view, or `hidden`. + "debug.toolBarLocation": "floating", + + // Global debug launch configuration. Should be used as an alternative to 'launch.json' that is shared across workspaces. + "launch": { + "configurations": [], + "compounds": [] + }, + +// HTML + + // Enable/disable autoclosing of HTML tags. + "html.autoClosingTags": true, + + // List of tags, comma separated, where the content shouldn't be reformatted. `null` defaults to the `pre` tag. + "html.format.contentUnformatted": "pre,code,textarea", + + // Enable/disable default HTML formatter. + "html.format.enable": true, + + // End with a newline. + "html.format.endWithNewline": false, + + // List of tags, comma separated, that should have an extra newline before them. `null` defaults to `"head, body, /html"`. + "html.format.extraLiners": "head, body, /html", + + // Format and indent `{{#foo}}` and `{{/foo}}`. + "html.format.indentHandlebars": false, + + // Indent `` and `` sections. + "html.format.indentInnerHtml": false, + + // Maximum number of line breaks to be preserved in one chunk. Use `null` for unlimited. + "html.format.maxPreserveNewLines": null, + + // Controls whether existing line breaks before elements should be preserved. Only works before elements, not inside tags or for text. + "html.format.preserveNewLines": true, + + // List of tags, comma separated, that shouldn't be reformatted. `null` defaults to all tags listed at https://www.w3.org/TR/html5/dom.html#phrasing-content. + "html.format.unformatted": "wbr", + + // Wrap attributes. + // - auto: Wrap attributes only when line length is exceeded. + // - force: Wrap each attribute except first. + // - force-aligned: Wrap each attribute except first and keep aligned. + // - force-expand-multiline: Wrap each attribute. + // - aligned-multiple: Wrap when line length is exceeded, align attributes vertically. + // - preserve: Preserve wrapping of attributes + // - preserve-aligned: Preserve wrapping of attributes but align. + "html.format.wrapAttributes": "auto", + + // Maximum amount of characters per line (0 = disable). + "html.format.wrapLineLength": 120, + + // Controls whether the built-in HTML language support suggests HTML5 tags, properties and values. + "html.suggest.html5": true, + + // Traces the communication between VS Code and the HTML language server. + "html.trace.server": "off", + + // Controls whether the built-in HTML language support validates embedded scripts. + "html.validate.scripts": true, + + // Controls whether the built-in HTML language support validates embedded styles. + "html.validate.styles": true, + +// JSON + + // Enable/disable default JSON formatter + "json.format.enable": true, + + // Associate schemas to JSON files in the current project + "json.schemas": [], + + // Traces the communication between VS Code and the JSON language server. + "json.trace.server": "off", + +// Markdown + + // Sets how line-breaks are rendered in the markdown preview. Setting it to 'true' creates a
for every newline. + "markdown.preview.breaks": false, + + // Double click in the markdown preview to switch to the editor. + "markdown.preview.doubleClickToSwitchToEditor": true, + + // Controls the font family used in the markdown preview. + "markdown.preview.fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe WPC', 'Segoe UI', 'Ubuntu', 'Droid Sans', sans-serif", + + // Controls the font size in pixels used in the markdown preview. + "markdown.preview.fontSize": 14, + + // Controls the line height used in the markdown preview. This number is relative to the font size. + "markdown.preview.lineHeight": 1.6, + + // Enable or disable conversion of URL-like text to links in the markdown preview. + "markdown.preview.linkify": true, + + // Mark the current editor selection in the markdown preview. + "markdown.preview.markEditorSelection": true, + + // How should clicking on links to markdown files be handled in the preview. + // - inPreview: Try to open links in the markdown preview + // - inEditor: Try to open links in the editor + "markdown.preview.openMarkdownLinks": "inPreview", + + // When a markdown preview is scrolled, update the view of the editor. + "markdown.preview.scrollEditorWithPreview": true, + + // When a markdown editor is scrolled, update the view of the preview. + "markdown.preview.scrollPreviewWithEditor": true, + + + // A list of URLs or local paths to CSS style sheets to use from the markdown preview. Relative paths are interpreted relative to the folder open in the explorer. If there is no open folder, they are interpreted relative to the location of the markdown file. All '\' need to be written as '\\'. + "markdown.styles": [], + + // Enable debug logging for the markdown extension. + "markdown.trace": "off", + +// PHP + + // Controls whether the built-in PHP language suggestions are enabled. The support suggests PHP globals and variables. + "php.suggest.basic": true, + + // Enable/disable built-in PHP validation. + "php.validate.enable": true, + + // Points to the PHP executable. + "php.validate.executablePath": null, + + // Whether the linter is run on save or on type. + "php.validate.run": "onSave", + +// TypeScript + + // Enable/disable automatic closing of JSX tags. Requires using TypeScript 3.0 or newer in the workspace. + "javascript.autoClosingTags": true, + + // Enable/disable default JavaScript formatter. + "javascript.format.enable": true, + + // Defines space handling after a comma delimiter. + "javascript.format.insertSpaceAfterCommaDelimiter": true, + + // Defines space handling after the constructor keyword. Requires using TypeScript 2.3.0 or newer in the workspace. + "javascript.format.insertSpaceAfterConstructor": false, + + // Defines space handling after function keyword for anonymous functions. + "javascript.format.insertSpaceAfterFunctionKeywordForAnonymousFunctions": true, + + // Defines space handling after keywords in a control flow statement. + "javascript.format.insertSpaceAfterKeywordsInControlFlowStatements": true, + + // Defines space handling after opening and before closing JSX expression braces. + "javascript.format.insertSpaceAfterOpeningAndBeforeClosingJsxExpressionBraces": false, + + // Defines space handling after opening and before closing non-empty braces. Requires using TypeScript 2.3.0 or newer in the workspace. + "javascript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces": true, + + // Defines space handling after opening and before closing non-empty brackets. + "javascript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBrackets": false, + + // Defines space handling after opening and before closing non-empty parenthesis. + "javascript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyParenthesis": false, + + // Defines space handling after opening and before closing template string braces. + "javascript.format.insertSpaceAfterOpeningAndBeforeClosingTemplateStringBraces": false, + + // Defines space handling after a semicolon in a for statement. + "javascript.format.insertSpaceAfterSemicolonInForStatements": true, + + // Defines space handling after a binary operator. + "javascript.format.insertSpaceBeforeAndAfterBinaryOperators": true, + + // Defines space handling before function argument parentheses. + "javascript.format.insertSpaceBeforeFunctionParenthesis": false, + + // Defines whether an open brace is put onto a new line for control blocks or not. + "javascript.format.placeOpenBraceOnNewLineForControlBlocks": false, + + // Defines whether an open brace is put onto a new line for functions or not. + "javascript.format.placeOpenBraceOnNewLineForFunctions": false, + + // Enable/disable semantic checking of JavaScript files. Existing jsconfig.json or tsconfig.json files override this setting. Requires using TypeScript 2.3.1 or newer in the workspace. + "javascript.implicitProjectConfig.checkJs": false, + + // Preferred path style for auto imports. + // - auto: Infer the shortest path type. + // - relative: Relative to the file location. + // - non-relative: Based on the `baseUrl` configured in your `jsconfig.json` / `tsconfig.json`. + "javascript.preferences.importModuleSpecifier": "auto", + + // Preferred quote style to use for quick fixes: `single` quotes, `double` quotes, or `auto` infer quote type from existing imports. Requires using TypeScript 2.9 or newer in the workspace. + "javascript.preferences.quoteStyle": "auto", + + // Enable/disable introducing aliases for object shorthand properties during renames. Requires using TypeScript 3.4 or newer in the workspace. + "javascript.preferences.renameShorthandProperties": true, + + // Enable/disable references CodeLens in JavaScript files. + "javascript.referencesCodeLens.enabled": false, + + // Enable/disable auto import suggestions. Requires using TypeScript 2.6.1 or newer in the workspace. + "javascript.suggest.autoImports": true, + + // Complete functions with their parameter signature. + "javascript.suggest.completeFunctionCalls": false, + + // Enable/disable suggestion to complete JSDoc comments. + "javascript.suggest.completeJSDocs": true, + + // Enabled/disable autocomplete suggestions. + "javascript.suggest.enabled": true, + + // Enable/disable including unique names from the file in JavaScript suggestions. + "javascript.suggest.names": true, + + // Enable/disable suggestions for paths in import statements and require calls. + "javascript.suggest.paths": true, + + // Enable/disable suggestion diagnostics for JavaScript files in the editor. Requires using TypeScript 2.8 or newer in the workspace. + "javascript.suggestionActions.enabled": true, + + // Enable/disable automatic updating of import paths when you rename or move a file in VS Code. Requires using TypeScript 2.9 or newer in the workspace. + // - prompt: Prompt on each rename. + // - always: Always update paths automatically. + // - never: Never rename paths and don't prompt. + "javascript.updateImportsOnFileMove.enabled": "prompt", + + // Enable/disable JavaScript validation. + "javascript.validate.enable": true, + + // Enable/disable automatic closing of JSX tags. Requires using TypeScript 3.0 or newer in the workspace. + "typescript.autoClosingTags": true, + + // Check if npm is installed for Automatic Type Acquisition. + "typescript.check.npmIsInstalled": true, + + // Disables automatic type acquisition. Automatic type acquisition fetches `@types` packages from npm to improve IntelliSense for external libraries. + "typescript.disableAutomaticTypeAcquisition": false, + + // Enable/disable default TypeScript formatter. + "typescript.format.enable": true, + + // Defines space handling after a comma delimiter. + "typescript.format.insertSpaceAfterCommaDelimiter": true, + + // Defines space handling after the constructor keyword. Requires using TypeScript 2.3.0 or newer in the workspace. + "typescript.format.insertSpaceAfterConstructor": false, + + // Defines space handling after function keyword for anonymous functions. + "typescript.format.insertSpaceAfterFunctionKeywordForAnonymousFunctions": true, + + // Defines space handling after keywords in a control flow statement. + "typescript.format.insertSpaceAfterKeywordsInControlFlowStatements": true, + + // Defines space handling after opening and before closing JSX expression braces. + "typescript.format.insertSpaceAfterOpeningAndBeforeClosingJsxExpressionBraces": false, + + // Defines space handling after opening and before closing non-empty braces. Requires using TypeScript 2.3.0 or newer in the workspace. + "typescript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces": true, + + // Defines space handling after opening and before closing non-empty brackets. + "typescript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBrackets": false, + + // Defines space handling after opening and before closing non-empty parenthesis. + "typescript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyParenthesis": false, + + // Defines space handling after opening and before closing template string braces. + "typescript.format.insertSpaceAfterOpeningAndBeforeClosingTemplateStringBraces": false, + + // Defines space handling after a semicolon in a for statement. + "typescript.format.insertSpaceAfterSemicolonInForStatements": true, + + // Defines space handling after type assertions in TypeScript. Requires using TypeScript 2.4 or newer in the workspace. + "typescript.format.insertSpaceAfterTypeAssertion": false, + + // Defines space handling after a binary operator. + "typescript.format.insertSpaceBeforeAndAfterBinaryOperators": true, + + // Defines space handling before function argument parentheses. + "typescript.format.insertSpaceBeforeFunctionParenthesis": false, + + // Defines whether an open brace is put onto a new line for control blocks or not. + "typescript.format.placeOpenBraceOnNewLineForControlBlocks": false, + + // Defines whether an open brace is put onto a new line for functions or not. + "typescript.format.placeOpenBraceOnNewLineForFunctions": false, + + // Enable/disable implementations CodeLens. This CodeLens shows the implementers of an interface. + "typescript.implementationsCodeLens.enabled": false, + + // Sets the locale used to report JavaScript and TypeScript errors. Requires using TypeScript 2.6.0 or newer in the workspace. Default of `null` uses VS Code's locale. + "typescript.locale": null, + + // Specifies the path to the npm executable used for Automatic Type Acquisition. Requires using TypeScript 2.3.4 or newer in the workspace. + "typescript.npm": null, + + // Preferred path style for auto imports. + // - auto: Infer the shortest path type. + // - relative: Relative to the file location. + // - non-relative: Based on the `baseUrl` configured in your `jsconfig.json` / `tsconfig.json`. + "typescript.preferences.importModuleSpecifier": "auto", + + // Preferred quote style to use for quick fixes: `single` quotes, `double` quotes, or `auto` infer quote type from existing imports. Requires using TypeScript 2.9 or newer in the workspace. + "typescript.preferences.quoteStyle": "auto", + + // Enable/disable introducing aliases for object shorthand properties during renames. Requires using TypeScript 3.4 or newer in the workspace. + "typescript.preferences.renameShorthandProperties": true, + + // Enable/disable references CodeLens in TypeScript files. + "typescript.referencesCodeLens.enabled": false, + + // Report style checks as warnings. + "typescript.reportStyleChecksAsWarnings": true, + + // Enable/disable auto import suggestions. Requires using TypeScript 2.6.1 or newer in the workspace. + "typescript.suggest.autoImports": true, + + // Complete functions with their parameter signature. + "typescript.suggest.completeFunctionCalls": false, + + // Enable/disable suggestion to complete JSDoc comments. + "typescript.suggest.completeJSDocs": true, + + // Enabled/disable autocomplete suggestions. + "typescript.suggest.enabled": true, + + // Enable/disable suggestions for paths in import statements and require calls. + "typescript.suggest.paths": true, + + // Enable/disable suggestion diagnostics for TypeScript files in the editor. Requires using TypeScript 2.8 or newer in the workspace. + "typescript.suggestionActions.enabled": true, + + // Controls auto detection of tsc tasks. + // - on: Create both build and watch tasks. + // - off: Disable this feature. + // - build: Only create single run compile tasks. + // - watch: Only create compile and watch tasks. + "typescript.tsc.autoDetect": "on", + + // Specifies the folder path containing the tsserver and lib*.d.ts files to use. + "typescript.tsdk": null, + + // Enables logging of the TS server to a file. This log can be used to diagnose TS Server issues. The log may contain file paths, source code, and other potentially sensitive information from your project. + "typescript.tsserver.log": "off", + + // Additional paths to discover Typescript Language Service plugins. Requires using TypeScript 2.3.0 or newer in the workspace. + "typescript.tsserver.pluginPaths": [], + + // Enables tracing of messages sent to the TS server. This trace can be used to diagnose TS Server issues. The trace may contain file paths, source code, and other potentially sensitive information from your project. + "typescript.tsserver.trace": "off", + + // Enable/disable automatic updating of import paths when you rename or move a file in VS Code. Requires using TypeScript 2.9 or newer in the workspace. + // - prompt: Prompt on each rename. + // - always: Always update paths automatically. + // - never: Never rename paths and don't prompt. + "typescript.updateImportsOnFileMove.enabled": "prompt", + + // Enable/disable TypeScript validation. + "typescript.validate.enable": true, + +// CSS + + // Invalid number of parameters. + "css.lint.argumentsInColorFunction": "error", + + // Do not use `width` or `height` when using `padding` or `border`. + "css.lint.boxModel": "ignore", + + // When using a vendor-specific prefix make sure to also include all other vendor-specific properties. + "css.lint.compatibleVendorPrefixes": "ignore", + + // Do not use duplicate style definitions. + "css.lint.duplicateProperties": "ignore", + + // Do not use empty rulesets. + "css.lint.emptyRules": "warning", + + // Avoid using `float`. Floats lead to fragile CSS that is easy to break if one aspect of the layout changes. + "css.lint.float": "ignore", + + // `@font-face` rule must define `src` and `font-family` properties. + "css.lint.fontFaceProperties": "warning", + + // Hex colors must consist of three or six hex numbers. + "css.lint.hexColorLength": "error", + + // Selectors should not contain IDs because these rules are too tightly coupled with the HTML. + "css.lint.idSelector": "ignore", + + // IE hacks are only necessary when supporting IE7 and older. + "css.lint.ieHack": "ignore", + + // Avoid using `!important`. It is an indication that the specificity of the entire CSS has gotten out of control and needs to be refactored. + "css.lint.important": "ignore", + + // Import statements do not load in parallel. + "css.lint.importStatement": "ignore", + + // Property is ignored due to the display. E.g. with `display: inline`, the `width`, `height`, `margin-top`, `margin-bottom`, and `float` properties have no effect. + "css.lint.propertyIgnoredDueToDisplay": "warning", + + // The universal selector (`*`) is known to be slow. + "css.lint.universalSelector": "ignore", + + // Unknown at-rule. + "css.lint.unknownAtRules": "warning", + + // Unknown property. + "css.lint.unknownProperties": "warning", + + // Unknown vendor specific property. + "css.lint.unknownVendorSpecificProperties": "ignore", + + // A list of properties that are not validated against the `unknownProperties` rule. + "css.lint.validProperties": [], + + // When using a vendor-specific prefix, also include the standard property. + "css.lint.vendorPrefix": "warning", + + // No unit for zero needed. + "css.lint.zeroUnits": "ignore", + + // Traces the communication between VS Code and the CSS language server. + "css.trace.server": "off", + + // Enables or disables all validations. + "css.validate": true, + +// LESS + + // Invalid number of parameters. + "less.lint.argumentsInColorFunction": "error", + + // Do not use `width` or `height` when using `padding` or `border`. + "less.lint.boxModel": "ignore", + + // When using a vendor-specific prefix make sure to also include all other vendor-specific properties. + "less.lint.compatibleVendorPrefixes": "ignore", + + // Do not use duplicate style definitions. + "less.lint.duplicateProperties": "ignore", + + // Do not use empty rulesets. + "less.lint.emptyRules": "warning", + + // Avoid using `float`. Floats lead to fragile CSS that is easy to break if one aspect of the layout changes. + "less.lint.float": "ignore", + + // `@font-face` rule must define `src` and `font-family` properties. + "less.lint.fontFaceProperties": "warning", + + // Hex colors must consist of three or six hex numbers. + "less.lint.hexColorLength": "error", + + // Selectors should not contain IDs because these rules are too tightly coupled with the HTML. + "less.lint.idSelector": "ignore", + + // IE hacks are only necessary when supporting IE7 and older. + "less.lint.ieHack": "ignore", + + // Avoid using `!important`. It is an indication that the specificity of the entire CSS has gotten out of control and needs to be refactored. + "less.lint.important": "ignore", + + // Import statements do not load in parallel. + "less.lint.importStatement": "ignore", + + // Property is ignored due to the display. E.g. with `display: inline`, the `width`, `height`, `margin-top`, `margin-bottom`, and `float` properties have no effect. + "less.lint.propertyIgnoredDueToDisplay": "warning", + + // The universal selector (`*`) is known to be slow. + "less.lint.universalSelector": "ignore", + + // Unknown property. + "less.lint.unknownProperties": "warning", + + // Unknown vendor specific property. + "less.lint.unknownVendorSpecificProperties": "ignore", + + // A list of properties that are not validated against the `unknownProperties` rule. + "less.lint.validProperties": [], + + // When using a vendor-specific prefix, also include the standard property. + "less.lint.vendorPrefix": "warning", + + // No unit for zero needed. + "less.lint.zeroUnits": "ignore", + + // Enables or disables all validations. + "less.validate": true, + +// SCSS (Sass) + + // Invalid number of parameters. + "scss.lint.argumentsInColorFunction": "error", + + // Do not use `width` or `height` when using `padding` or `border`. + "scss.lint.boxModel": "ignore", + + // When using a vendor-specific prefix make sure to also include all other vendor-specific properties. + "scss.lint.compatibleVendorPrefixes": "ignore", + + // Do not use duplicate style definitions. + "scss.lint.duplicateProperties": "ignore", + + // Do not use empty rulesets. + "scss.lint.emptyRules": "warning", + + // Avoid using `float`. Floats lead to fragile CSS that is easy to break if one aspect of the layout changes. + "scss.lint.float": "ignore", + + // `@font-face` rule must define `src` and `font-family` properties. + "scss.lint.fontFaceProperties": "warning", + + // Hex colors must consist of three or six hex numbers. + "scss.lint.hexColorLength": "error", + + // Selectors should not contain IDs because these rules are too tightly coupled with the HTML. + "scss.lint.idSelector": "ignore", + + // IE hacks are only necessary when supporting IE7 and older. + "scss.lint.ieHack": "ignore", + + // Avoid using `!important`. It is an indication that the specificity of the entire CSS has gotten out of control and needs to be refactored. + "scss.lint.important": "ignore", + + // Import statements do not load in parallel. + "scss.lint.importStatement": "ignore", + + // Property is ignored due to the display. E.g. with `display: inline`, the `width`, `height`, `margin-top`, `margin-bottom`, and `float` properties have no effect. + "scss.lint.propertyIgnoredDueToDisplay": "warning", + + // The universal selector (`*`) is known to be slow. + "scss.lint.universalSelector": "ignore", + + // Unknown property. + "scss.lint.unknownProperties": "warning", + + // Unknown vendor specific property. + "scss.lint.unknownVendorSpecificProperties": "ignore", + + // A list of properties that are not validated against the `unknownProperties` rule. + "scss.lint.validProperties": [], + + // When using a vendor-specific prefix, also include the standard property. + "scss.lint.vendorPrefix": "warning", + + // No unit for zero needed. + "scss.lint.zeroUnits": "ignore", + + // Enables or disables all validations. + "scss.validate": true, + +// Extensions + +// When enabled, automatically checks extensions for updates. If an extension has an update, it is marked as outdated in the Extensions view. The updates are fetched from a Microsoft online service. + "extensions.autoCheckUpdates": true, + + // When enabled, automatically installs updates for extensions. The updates are fetched from a Microsoft online service. + "extensions.autoUpdate": true, + + // When enabled, editors with extension details will be automatically closed upon navigating away from the Extensions View. + "extensions.closeExtensionDetailsOnViewChange": false, + + // When enabled, the notifications for extension recommendations will not be shown. + "extensions.ignoreRecommendations": false, + + // When enabled, recommendations will not be fetched or shown unless specifically requested by the user. Some recommendations are fetched from a Microsoft online service. + "extensions.showRecommendationsOnlyOnDemand": false, + +// External Terminal + + // Customizes what kind of terminal to launch. + // - integrated: Use VS Code's integrated terminal. + // - external: Use the configured external terminal. + "terminal.explorerKind": "integrated", + + // Customizes which terminal to run on Linux. + "terminal.external.linuxExec": "xterm", + + // Customizes which terminal application to run on macOS. + "terminal.external.osxExec": "Terminal.app", + + // Customizes which terminal to run on Windows. + "terminal.external.windowsExec": "C:\\WINDOWS\\System32\\cmd.exe", + +// Integrated Terminal + + // A set of command IDs whose keybindings will not be sent to the shell and instead always be handled by Code. This allows the use of keybindings that would normally be consumed by the shell to act the same as when the terminal is not focused, for example ctrl+p to launch Quick Open. + "terminal.integrated.commandsToSkipShell": [], + + // Controls whether to confirm on exit if there are active terminal sessions. + "terminal.integrated.confirmOnExit": false, + + // Controls whether text selected in the terminal will be copied to the clipboard. + "terminal.integrated.copyOnSelection": false, + + // Controls whether the terminal cursor blinks. + "terminal.integrated.cursorBlinking": false, + + // Controls the style of terminal cursor. + "terminal.integrated.cursorStyle": "block", + + // An explicit start path where the terminal will be launched, this is used as the current working directory (cwd) for the shell process. This may be particularly useful in workspace settings if the root directory is not a convenient cwd. + "terminal.integrated.cwd": "", + + // Controls whether bold text in the terminal will always use the "bright" ANSI color variant. + "terminal.integrated.drawBoldTextInBrightColors": true, + + // Controls whether the terminal bell is enabled. + "terminal.integrated.enableBell": false, + + // Object with environment variables that will be added to the VS Code process to be used by the terminal on Linux. Set to `null` to delete the environment variable. + "terminal.integrated.env.linux": {}, + + // Object with environment variables that will be added to the VS Code process to be used by the terminal on macOS. Set to `null` to delete the environment variable. + "terminal.integrated.env.osx": {}, + + // Object with environment variables that will be added to the VS Code process to be used by the terminal on Windows. Set to `null` to delete the environment variable. + "terminal.integrated.env.windows": {}, + + // Controls the font family of the terminal, this defaults to `editor.fontFamily`'s value. + "terminal.integrated.fontFamily": "", + + // Controls the font size in pixels of the terminal. + "terminal.integrated.fontSize": 14, + + // The font weight to use within the terminal for non-bold text. + "terminal.integrated.fontWeight": "normal", + + // The font weight to use within the terminal for bold text. + "terminal.integrated.fontWeightBold": "bold", + + // Controls the letter spacing of the terminal, this is an integer value which represents the amount of additional pixels to add between characters. + "terminal.integrated.letterSpacing": 0, + + // Controls the line height of the terminal, this number is multiplied by the terminal font size to get the actual line-height in pixels. + "terminal.integrated.lineHeight": 1, + + // Controls whether to force selection when using Option+click on macOS. This will force a regular (line) selection and disallow the use of column selection mode. This enables copying and pasting using the regular terminal selection, for example, when mouse mode is enabled in tmux. + "terminal.integrated.macOptionClickForcesSelection": false, + + // Controls whether to treat the option key as the meta key in the terminal on macOS. + "terminal.integrated.macOptionIsMeta": false, + + // Controls how the terminal is rendered. + // - auto: Let VS Code guess which renderer to use. + // - canvas: Use the standard GPU/canvas-based renderer + // - dom: Use the fallback DOM-based renderer. + "terminal.integrated.rendererType": "auto", + + // Controls how terminal reacts to right click. + // - default: Show the context menu. + // - copyPaste: Copy when there is a selection, otherwise paste. + // - selectWord: Select the word under the cursor and show the context menu. + "terminal.integrated.rightClickBehavior": "copyPaste", + + // Controls the maximum amount of lines the terminal keeps in its buffer. + "terminal.integrated.scrollback": 1000, + + // Controls whether locale variables are set at startup of the terminal. + "terminal.integrated.setLocaleVariables": true, + + // The path of the shell that the terminal uses on Linux. [Read more about configuring the shell](https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration). + "terminal.integrated.shell.linux": "/bin/bash", + + // The path of the shell that the terminal uses on macOS. [Read more about configuring the shell](https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration). + "terminal.integrated.shell.osx": "/bin/bash", + + // The path of the shell that the terminal uses on Windows. [Read more about configuring the shell](https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration). + "terminal.integrated.shell.windows": "C:\\WINDOWS\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", + + // The command line arguments to use when on the Linux terminal. [Read more about configuring the shell](https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration). + "terminal.integrated.shellArgs.linux": [], + + // The command line arguments to use when on the macOS terminal. [Read more about configuring the shell](https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration). + "terminal.integrated.shellArgs.osx": [ + "-l" + ], + + // The command line arguments to use when on the Windows terminal. [Read more about configuring the shell](https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration). + "terminal.integrated.shellArgs.windows": [], + + // Controls whether to show the alert "The terminal process terminated with exit code" when exit code is non-zero. + "terminal.integrated.showExitAlert": true, + + // Controls the working directory a split terminal starts with. + // - workspaceRoot: A new split terminal will use the workspace root as the working directory. In a multi-root workspace a choice for which root folder to use is offered. + // - initial: A new split terminal will use the working directory that the parent terminal started with. + // - inherited: On macOS and Linux, a new split terminal will use the working directory of the parent terminal. On Windows, this behaves the same as initial. + "terminal.integrated.splitCwd": "inherited", + +// Problems + + // Controls whether Problems view should automatically reveal files when opening them. + "problems.autoReveal": true, + + // Show Errors & Warnings on files and folder. + "problems.decorations.enabled": true, + +// Breadcrumb Navigation + + // Enable/disable navigation breadcrumbs. + "breadcrumbs.enabled": false, + + // Controls whether and how file paths are shown in the breadcrumbs view. + // - on: Show the file path in the breadcrumbs view. + // - off: Do not show the file path in the breadcrumbs view. + // - last: Only show the last element of the file path in the breadcrumbs view. + "breadcrumbs.filePath": "on", + + // Controls whether and how symbols are shown in the breadcrumbs view. + // - on: Show all symbols in the breadcrumbs view. + // - off: Do not show symbols in the breadcrumbs view. + // - last: Only show the current symbol in the breadcrumbs view. + "breadcrumbs.symbolPath": "on", + + // Controls how symbols are sorted in the breadcrumbs outline view. + // - position: Show symbol outline in file position order. + // - name: Show symbol outline in alphabetical order. + // - type: Show symbol outline in symbol type order. + "breadcrumbs.symbolSortOrder": "position", + +// Telemetry + + // Enable crash reports to be sent to a Microsoft online service. + // This option requires restart to take effect. + "telemetry.enableCrashReporter": true, + + // Enable usage data and errors to be sent to a Microsoft online service. + "telemetry.enableTelemetry": true, + +// Outline + + // Render Outline Elements with Icons. + "outline.icons": true, + + // Use badges for Errors & Warnings. + "outline.problems.badges": true, + + // Use colors for Errors & Warnings. + "outline.problems.colors": true, + + // Show Errors & Warnings on Outline Elements. + "outline.problems.enabled": true, + +// Git + + // Controls whether force push (with or without lease) is enabled. + "git.allowForcePush": false, + + // Always show the Staged Changes resource group. + "git.alwaysShowStagedChangesResourceGroup": false, + + // Controls the signoff flag for all commits. + "git.alwaysSignOff": false, + + // When enabled, commits will automatically be fetched from the default remote of the current Git repository. + "git.autofetch": false, + + // Duration in seconds between each automatic git fetch, when `git.autofetch` is enabled. + "git.autofetchPeriod": 180, + + // Whether auto refreshing is enabled. + "git.autorefresh": true, + + // Configures when repositories should be automatically detected. + // - true: Scan for both subfolders of the current opened folder and parent folders of open files. + // - false: Disable automatic repository scanning. + // - subFolders: Scan for subfolders of the currently opened folder. + // - openEditors: Scan for parent folders of open files. + "git.autoRepositoryDetection": true, + + // Stash any changes before pulling and restore them after successful pull. + "git.autoStash": false, + + // A regular expression to validate new branch names. + "git.branchValidationRegex": "", + + // The character to replace whitespace in new branch names. + "git.branchWhitespaceChar": "-", + + // Controls what type of branches are listed when running `Checkout to...`. + // - all: Show all references. + // - local: Show only local branches. + // - tags: Show only tags. + // - remote: Show only remote branches. + "git.checkoutType": "all", + + // Always confirm the creation of empty commits. + "git.confirmEmptyCommits": true, + + // Controls whether to ask for confirmation before force-pushing. + "git.confirmForcePush": true, + + // Confirm before synchronizing git repositories. + "git.confirmSync": true, + + // Controls the git badge counter. + // - all: Count all changes. + // - tracked: Count only tracked changes. + // - off: Turn off counter. + "git.countBadge": "all", + + // Controls whether Git contributes colors and badges to the explorer and the open editors view. + "git.decorations.enabled": true, + + // The default location to clone a git repository. + "git.defaultCloneDirectory": null, + + // Controls whether to automatically detect git submodules. + "git.detectSubmodules": true, + + // Controls the limit of git submodules detected. + "git.detectSubmodulesLimit": 10, + + // Enables commit signing with GPG. + "git.enableCommitSigning": false, + + // Whether git is enabled. + "git.enabled": true, + + // Commit all changes when there are no staged changes. + "git.enableSmartCommit": false, + + // Fetch all branches when pulling or just the current one. + "git.fetchOnPull": false, + + // List of git repositories to ignore. + "git.ignoredRepositories": [], + + // Ignores the legacy Git warning. + "git.ignoreLegacyWarning": false, + + // Ignores the warning when there are too many changes in a repository. + "git.ignoreLimitWarning": false, + + // Ignores the warning when Git is missing. + "git.ignoreMissingGitWarning": false, + + // Controls when to show commit message input validation. + "git.inputValidation": "warn", + + // Controls the commit message length threshold for showing a warning. + "git.inputValidationLength": 72, + + // Controls the commit message subject length threshold for showing a warning. Unset it to inherit the value of `config.inputValidationLength`. + "git.inputValidationSubjectLength": 50, + + // Controls whether the diff editor should be opened when clicking a change. Otherwise the regular editor will be opened. + "git.openDiffOnClick": true, + + // Path and filename of the git executable, e.g. `C:\Program Files\Git\bin\git.exe` (Windows). + "git.path": null, + + // Runs a git command after a successful commit. + // - none: Don't run any command after a commit. + // - push: Run 'Git Push' after a successful commit. + // - sync: Run 'Git Sync' after a successful commit. + "git.postCommitCommand": "none", + + // Controls whether Git should check for unsaved files before committing. + "git.promptToSaveFilesBeforeCommit": true, + + // Force git to use rebase when running the sync command. + "git.rebaseWhenSync": false, + + // List of paths to search for git repositories in. + "git.scanRepositories": [], + + // Controls whether to show an inline Open File action in the Git changes view. + "git.showInlineOpenFileAction": true, + + // Controls whether git actions should show progress. + "git.showProgress": true, + + // Controls whether to show a notification when a push is successful. + "git.showPushSuccessNotification": false, + + // Controls whether force pushing uses the safer force-with-lease variant. + "git.useForcePushWithLease": true, + +// Default Configuration Overrides + + // Configure editor settings to be overridden for [git-commit] language. + "[git-commit]": { + "editor.rulers": [ + 72 + ] + }, + + // Configure editor settings to be overridden for [go] language. + "[go]": { + "editor.insertSpaces": false + }, + + // Configure editor settings to be overridden for [json] language. + "[json]": { + "editor.quickSuggestions": { + "strings": true + } + }, + + // Configure editor settings to be overridden for [makefile] language. + "[makefile]": { + "editor.insertSpaces": false + }, + + // Configure editor settings to be overridden for [markdown] language. + "[markdown]": { + "editor.wordWrap": "on", + "editor.quickSuggestions": false + }, + + // Configure editor settings to be overridden for [yaml] language. + "[yaml]": { + "editor.insertSpaces": true, + "editor.tabSize": 2, + "editor.autoIndent": false + }, + +// Node debug + + // Automatically attach node debugger when node.js was launched in debug mode from integrated terminal. + // - disabled: Auto attach is disabled and not shown in status bar. + // - on: Auto attach is active. + // - off: Auto attach is inactive. + "debug.node.autoAttach": "disabled", + +// Npm + + // Controls whether npm scripts should be automatically detected. + "npm.autoDetect": "on", + + // Enable an explorer view for npm scripts. + "npm.enableScriptExplorer": false, + + // Configure glob patterns for folders that should be excluded from automatic script detection. + "npm.exclude": "", + + // Fetch data from https://registry.npmjs/org and https://registry.bower.io to provide auto-completion and information on hover features on npm dependencies. + "npm.fetchOnlinePackageInfo": true, + + // The package manager used to run scripts. + "npm.packageManager": "npm", + + // Run npm commands with the `--silent` option. + "npm.runSilent": false, + + // The default click action used in the scripts explorer: `open` or `run`, the default is `open`. + "npm.scriptExplorerAction": "open", + +// Reference Search View + + // Controls whether 'Peek References' or 'Find References' is invoked when selecting code lens references + // - peek: Show references in peek editor. + // - view: Show references in separate view. + "references.preferredLocation": "peek", + +// Merge Conflict + + // Whether to automatically navigate to the next merge conflict after resolving a merge conflict. + "merge-conflict.autoNavigateNextConflict.enabled": false, + + // Create a Code Lens for merge conflict blocks within editor. + "merge-conflict.codeLens.enabled": true, + + // Create decorators for merge conflict blocks within editor. + "merge-conflict.decorators.enabled": true, + +// Emmet + + // An array of languages where Emmet abbreviations should not be expanded. + "emmet.excludeLanguages": [ + "markdown" + ], + + // Path to a folder containing Emmet profiles and snippets. + "emmet.extensionsPath": null, + + // Enable Emmet abbreviations in languages that are not supported by default. Add a mapping here between the language and emmet supported language. + // E.g.: `{"vue-html": "html", "javascript": "javascriptreact"}` + "emmet.includeLanguages": {}, + + // When set to `false`, the whole file is parsed to determine if current position is valid for expanding Emmet abbreviations. When set to `true`, only the content around the current position in css/scss/less files is parsed. + "emmet.optimizeStylesheetParsing": true, + + // Preferences used to modify behavior of some actions and resolvers of Emmet. + "emmet.preferences": {}, + + // Shows possible Emmet abbreviations as suggestions. Not applicable in stylesheets or when emmet.showExpandedAbbreviation is set to `"never"`. + "emmet.showAbbreviationSuggestions": true, + + // Shows expanded Emmet abbreviations as suggestions. + // The option `"inMarkupAndStylesheetFilesOnly"` applies to html, haml, jade, slim, xml, xsl, css, scss, sass, less and stylus. + // The option `"always"` applies to all parts of the file regardless of markup/css. + "emmet.showExpandedAbbreviation": "always", + + // If `true`, then Emmet suggestions will show up as snippets allowing you to order them as per `editor.snippetSuggestions` setting. + "emmet.showSuggestionsAsSnippets": false, + + // Define profile for specified syntax or use your own profile with specific rules. + "emmet.syntaxProfiles": {}, + + // When enabled, Emmet abbreviations are expanded when pressing TAB. + "emmet.triggerExpansionOnTab": false, + + // Variables to be used in Emmet snippets + "emmet.variables": {}, + +// Jake + + // Controls whether auto detection of Jake tasks is on or off. Default is on. + "jake.autoDetect": "on", + + // Controls whether auto detection of Grunt tasks is on or off. Default is on. + "grunt.autoDetect": "on", + +// Gulp + + // Controls whether auto detection of Gulp tasks is on or off. Default is on. + "gulp.autoDetect": "on", +} +``` + +## Common questions + +### VS Code says "Unable to write settings." + +If you try to change a setting (for example turning on Auto Save or selecting a new Color Theme) and you see "Unable to write settings. Please open User Settings to correct errors/warnings in the file and try again.", it means your `settings.json` file is ill-formed or has errors. The errors can be as simple as a missing comma or setting value. Open the Settings editor **File** > **Preferences** > **Settings** (**Code** > **Preferences** > **Settings** on macOS) (`kb(workbench.action.openSettings)`) and you should see the error highlighted with red squiggles. + +### How can I reset my user settings? + +The easiest way to reset VS Code back to the default settings is to clear your user `settings.json` file contents in the Settings editor. Delete everything between the two curly braces, save the file, and VS Code will go back to using the default values. + +### When does it make sense to use workspace settings? + +If you're using a workspace that needs custom settings but you don't want to apply them to your other VS Code projects. A good example is language-specific linting rules. diff --git a/docs/getstarted/themes.md b/docs/getstarted/themes.md new file mode 100644 index 0000000000000000000000000000000000000000..998ca748e7028c3916db66c5858ffbb033d17d01 --- /dev/null +++ b/docs/getstarted/themes.md @@ -0,0 +1,144 @@ +--- +Order: 5 +Area: getstarted +TOCTitle: Themes +ContentId: CAC88BC7-90A5-4384-8A05-2187117C0F72 +PageTitle: Visual Studio Code Themes +DateApproved: 3/7/2019 +MetaDescription: Changing the color theme in Visual Studio Code. You can use color themes provided by VS Code, the community or create your own new themes. +--- +# Color Themes + +Color themes let you modify the colors in Visual Studio Code's user interface to suit your preferences and work environment. + +![Preview themes from the Command Palette](images/themes/themes_hero.gif) + +## Selecting the Color Theme + +1. In VS Code, open the Color Theme picker with **File** > **Preferences** > **Color Theme**. (**Code** > **Preferences** > **Color Theme** on macOS). +2. You can also use the keyboard shortcut `kb(workbench.action.selectTheme)` to display the picker. +3. Use the cursor keys to preview the colors of the theme. +4. Select the theme you want and press `kbstyle(Enter)`. + +![Themes in the Command Palette](images/themes/colorthemes.png) + +The active color theme is stored in your user [settings](/docs/getstarted/settings.md) (keyboard shortcut `kb(workbench.action.openSettings)`). + +```json + // Specifies the color theme used in the workbench. + "workbench.colorTheme": "Default Dark+" +} +``` + +> **Tip:** By default, the theme is stored in your user settings and applies globally to all workspaces. You can also configure a workspace specific theme. To do so, set a theme in the Workspace [settings](/docs/getstarted/settings.md#creating-user-and-workspace-settings). + +## Color Themes from the Marketplace + +There are several out-of-the-box color themes in VS Code for you to try. + +Many more themes have been uploaded to the VS Code [Extension Marketplace](/docs/editor/extension-gallery.md) by the community. If you find one you want to use, install it and restart VS Code and the new theme will be available. + +> **Tip:** To search for themes, type 'theme' in the Extensions view (`kb(workbench.view.extensions)`) search box. + +
+ +You can also browse the [VS Code Marketplace](https://marketplace.visualstudio.com/vscode/Themes) site directly to find available themes. + +## Customizing a Color Theme + +You can customize your active color theme with the `workbench.colorCustomizations` and `editor.tokenColorCustomizations` user [settings](/docs/getstarted/settings.md). + +To set the colors of VS Code UI elements such as list & trees (File Explorer, suggestions widget), diff editor, Activity Bar, notifications, scroll bar, split view, buttons and more, use `workbench.colorCustomizations`. + +![activity bar theming](images/themes/theme-activitybar.gif) + +You can use IntelliSense while setting `workbench.colorCustomizations` values or, for a list of all customizable colors, see the [Theme Color Reference](/docs/getstarted/theme-color-reference.md). + +To customize a specific theme only, use the following syntax: + +```json +"workbench.colorCustomizations": { + "[Monokai]": { + "sideBar.background": "#347890" + } +} +``` + +To tune the editor's syntax highlighting colors, use `editor.tokenColorCustomizations` in your user [settings](/docs/getstarted/settings.md) `settings.json` file: + +![Token Color Customization](images/themes/token_color_customization.png) + +A pre-configured set of syntax tokens ('comments', 'strings', ...) is available for the most common constructs. If you want more, you can do so by directly specifying TextMate theme color rules: + +![Advanced Token Color Customization](images/themes/token_color_customization_advanced.png) + +>**Note**: Directly configuring TextMate rules is an advanced skill as you need to understand on how TextMate grammars work. Go [here](/api/extension-guides/color-theme.md) for more information. + +Again, to customize a specific theme only, use the following syntax: + +```json +"editor.tokenColorCustomizations": { + "[Monokai]": { + "comments": "#229977" + } +}, +``` + +## Creating your own Color Theme + +Creating and publishing a theme extension is quite easy. Customize your colors in your user settings then generate a theme definition file with the **Developer: Generate Color Theme From Current Settings** command. + +VS Code's Yeoman [extension generator](/api/get-started/your-first-extension.md) will help you generate the rest of the extension. + +See the [Create a new Color Theme](/api/extension-guides/color-theme.md#create-a-new-color-theme) topic in our Extension API section to learn more. + +## Remove default themes + +If you'd like to remove some of the default themes shipped with VS Code from the Color Theme picker, you can disable them from the Extensions view (`kb(workbench.view.extensions)`). Open the `...` **More Actions** drop-down menu from the top of the Extensions view, select **Show Built-in Extensions**, and you'll see a **THEMES** section listing the default themes. + +![built-in themes](images/themes/built-in-themes.png) + +You can disable a built-in theme extension as you would any other VS Code [extension](/docs/editor/extension-gallery.md) with the **Disable** command on the gear context menu. + +![disable theme](images/themes/disable-theme.png) + +# Icon Themes + +File icon themes can be contributed by extensions and selected by users as their favorite set of file icons. File icons are shown in the File Explorer and tabbed headings. + +## Selecting the File Icon Theme + +1. In VS Code, open the File Icon Theme picker with **File** > **Preferences** > **File Icon Theme**. (**Code** > **Preferences** > **File Icon Theme** on macOS). +2. You can also use the **Preferences: File Icon Theme** command from the **Command Palette** (`kb(workbench.action.showCommands)`). +3. Use the cursor keys to preview the icons of the theme. +4. Select the theme you want and hit `kbstyle(Enter)`. + +![file icon theme drop-down](images/themes/file-icon-theme-dropdown.png) + +By default, the **Seti** file icon set is used and those are the icons you see in the File Explorer. Once an icon theme is selected, the selected theme will be remembered and appear again whenever VS Code is restarted. You can disable file icons by selecting **None**. + +VS code ships with two icon themes; **Minimal** and **Seti**. To install more icon themes, select the **Install Additional File Icon Themes** item in the icon theme picker and you'll see a query for file icon themes (tag:icon-theme) in the Extensions view. + +You can also browse the [VS Code Marketplace](https://marketplace.visualstudio.com/vscode/Themes) site directly to find available themes. + +The active File Icon theme is persisted in your user [settings](/docs/getstarted/settings.md) (keyboard shortcut `kb(workbench.action.openSettings)`). + +```json + // Specifies the icon theme used in the workbench. + "workbench.iconTheme": "vs-seti" +} +``` + +## Creating your own File Icon Theme + +You can create your own File Icon Theme from icons (preferably SVG), see the [Icon Theme](/api/extension-guides/icon-theme.md) topic in our Extension API section for details. + +## Next steps + +Themes are just one way to customize VS Code. If you'd like to learn more about VS Code customization and extensibility, try these topics: + +* [Settings](/docs/getstarted/settings) - Learn how to configure VS Code to your preferences through user and workspace settings. +* [Snippets](/docs/editor/userdefinedsnippets.md) - Add additional snippets to your favorite language. +* [Extension API](/api) - Learn about other ways to extend VS Code. +* [Color Theme](/api/extension-guides/color-theme.md) - Color Theme extension API. +* [Icon Theme](/api/extension-guides/icon-theme.md) - Icon Theme extension API. diff --git a/docs/getstarted/tips-and-tricks.md b/docs/getstarted/tips-and-tricks.md new file mode 100644 index 0000000000000000000000000000000000000000..decc09478061b28cb841295f71a76d816fe759fe --- /dev/null +++ b/docs/getstarted/tips-and-tricks.md @@ -0,0 +1,896 @@ +--- +Order: 3 +Area: getstarted +TOCTitle: Tips and Tricks +ContentId: 9bbbe55d-cf81-428f-8a9f-4f60280cb874 +PageTitle: Visual Studio Code Tips and Tricks +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code Tips and Tricks for power users. +--- +# Visual Studio Code Tips and Tricks + +"Tips and Tricks" lets you jump right in and learn how to be productive with Visual Studio Code. You'll become familiar with its powerful editing, code intelligence, and source code control features and learn useful keyboard shortcuts. This topic goes pretty fast and provides a broad overview, so be sure to look at the other in-depth topics in [Getting Started](/docs/getstarted/userinterface.md) and the [User Guide](/docs/editor/codebasics.md) to learn more. + +> If you don't have Visual Studio Code installed, go to the [Download](/download) page. You can find platform specific setup instructions at [Running VS Code on Linux](/docs/setup/linux.md), [macOS](/docs/setup/mac.md), and [Windows](/docs/setup/windows.md). + +## Basics + +### Getting started + +Open the **Welcome** page to get started with the basics of VS Code. **Help** > **Welcome**. + +![welcome page](images/tips-and-tricks/welcome_page.png) + +In the bottom right of the **Welcome** page, there is a link to the **Interactive playground** where you can interactively try out VS Code's features. **Help** > **Interactive Playground**. + +![interactive playground](images/tips-and-tricks/interactive_playground.png) + +### Command Palette + +Access all available commands based on your current context. + +Keyboard Shortcut: `kb(workbench.action.showCommands)` + +![command palette](images/tips-and-tricks/OpenCommandPalatte.gif) + +### Default keyboard shortcuts + +All of the commands are in the **Command Palette** with the associated key binding (if it exists). If you forget a keyboard shortcut, use the **Command Palette** to help you out. + +![keyboard references](images/tips-and-tricks/keyboard-references.png) + +### Keyboard reference sheets + +Download the keyboard shortcut reference sheet for your platform ([macOS](https://go.microsoft.com/fwlink/?linkid=832143), [Windows](https://go.microsoft.com/fwlink/?linkid=832145), [Linux](https://go.microsoft.com/fwlink/?linkid=832144)). + +![Keyboard Reference Sheet](images/tips-and-tricks/KeyboardReferenceSheet.png) + +### Quick Open + +Quickly open files. + +Keyboard Shortcut: `kb(workbench.action.quickOpen)` + +![Quick Open](images/tips-and-tricks/QuickOpen.gif) + +**Tip:** Type `kbstyle(?)` to view help suggestions. + +### Navigate between recently opened files + +Repeat the **Quick Open** keyboard shortcut to cycle quickly between recently opened files. + +### Open multiple files from Quick Open + +You can open multiple files from **Quick Open** by pressing the Right arrow key. This will open the currently selected file in the background and you can continue selecting files from **Quick Open**. + +## Command line + +VS Code has a powerful command line interface (CLI) which allows you to customize how the editor is launched to support various scenarios. + +> Make sure the VS Code binary is on your path so you can simply type 'code' to launch VS Code. See the platform specific setup topics if VS Code is added to your environment path during installation ([Running VS Code on Linux](/docs/setup/linux.md), [macOS](/docs/setup/mac.md), [Windows](/docs/setup/windows.md)). + +```bash +# open code with current directory +code . + +# open the current directory in the most recently used code window +code -r . + +# create a new window +code -n + +# change the language +code --locale=es + +# open diff editor +code --diff + +# open file at specific line and column +code --goto package.json:10:5 + +# see help options +code --help + +# disable all extensions +code --disable-extensions . +``` + +### .vscode folder + +Workspace specific files are in a `.vscode` folder at the root. For example, `tasks.json` for the Task Runner and `launch.json` for the debugger. + +## Status Bar + +### Errors and warnings + +Keyboard Shortcut: `kb(workbench.actions.view.problems)` + +Quickly jump to errors and warnings in the project. + +Cycle through errors with `kb(editor.action.marker.nextInFiles)` or `kb(editor.action.marker.prevInFiles)` + +![errors and warnings](images/tips-and-tricks/Errors_Warnings.gif) + +You can filter problems by type ('errors', 'warnings') or text matching. + +### Change language mode + +Keyboard Shortcut: `kb(workbench.action.editor.changeLanguageMode)` + +![change syntax](images/tips-and-tricks/change_syntax.gif) + +If you want to persist the new language mode for that file type, you can use the **Configure File Association for** command to associate the current file extension with an installed language. + +## Customization + +There are many things you can do to customize VS Code. + +* Change your theme +* Change your keyboard shortcuts +* Tune your settings +* Add JSON validation +* Create snippets +* Install extensions + +### Change your theme + +Keyboard Shortcut: `kb(workbench.action.selectTheme)` + +You can install more themes from the VS Code extension [Marketplace](https://marketplace.visualstudio.com/search?target=VSCode&category=Themes&sortBy=Downloads). + +![Preview themes](images/tips-and-tricks/PreviewThemes.gif) + +Additionally, you can install and change your File Icon themes. + +![File icon themes](images/tips-and-tricks/PreviewFileIconThemes.gif) + +### Keymaps + +Are you used to keyboard shortcuts from another editor? You can install a Keymap extension that brings the keyboard shortcuts from your favorite editor to VS Code. Go to **Preferences** > **Keymap Extensions** to see the current list on the [Marketplace](https://marketplace.visualstudio.com/search?target=VSCode&category=Keymaps&sortBy=Downloads). Some of the more popular ones: + +* [Vim](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) +* [Sublime Text Keymap](https://marketplace.visualstudio.com/items?itemName=ms-vscode.sublime-keybindings) +* [Emacs Keymap](https://marketplace.visualstudio.com/items?itemName=hiro-sun.vscode-emacs) +* [Atom Keymap](https://marketplace.visualstudio.com/items?itemName=ms-vscode.atom-keybindings) +* [Eclipse Keymap](https://marketplace.visualstudio.com/items?itemName=alphabotsec.vscode-eclipse-keybindings) + +### Customize your keyboard shortcuts + +Keyboard Shortcut: `kb(workbench.action.openGlobalKeybindings)` + +![keyboard shortcuts](images/tips-and-tricks/keyboard-shortcuts.png) + +You can search for shortcuts and add your own keybindings to the `keybindings.json` file. + +![customize keyboard shortcuts](images/tips-and-tricks/KeyboardShortcuts.gif) + +See more in [Key Bindings for Visual Studio Code](/docs/getstarted/keybindings.md). + +### Tune your settings + +By default VS Code shows the Settings editor, you can find settings listed below in a search bar, but you can still edit the underlying `settings.json` file by using the **Open Settings (JSON)** command or by changing your default settings editor with the `workbench.settings.editor` setting. + +Open User Settings `settings.json` + +Keyboard Shortcut: `kb(workbench.action.openSettings)` + +Format on paste + +```json +"editor.formatOnPaste": true +``` + +Change the font size of various UI elements + +```json +// Main editor +"editor.fontSize": 18, +// Terminal panel +"terminal.integrated.fontSize": 14, +// Output panel +"[Log]": { + "editor.fontSize": 15 +} +``` + +Change the zoom level + +```json +"window.zoomLevel": 5 +``` + +Font ligatures + +```json +"editor.fontFamily": "Fira Code", +"editor.fontLigatures": true +``` + +> **Tip:** You will need to have a font installed that supports font ligatures. [FiraCode](https://github.com/tonsky/FiraCode) is a popular font on the VS Code team. + +![font ligatures](images/tips-and-tricks/font-ligatures-annotated.png) + +Auto Save + +```json +"files.autoSave": "afterDelay" +``` + +You can also toggle Auto Save from the top-level menu with the **File** > **Auto Save**. + +Format on save + +```json +"editor.formatOnSave": true +``` + +Change the size of Tab characters + +```json +"editor.tabSize": 4 +``` + +Spaces or Tabs + +```json +"editor.insertSpaces": true +``` + +Render whitespace + +```json +"editor.renderWhitespace": "all" +``` + +Ignore files / folders + +Removes these files / folders from your editor window. + +```json +"files.exclude": { + "somefolder/": true, + "somefile": true +} +``` + +Remove these files / folders from search results. + +```json +"search.exclude": { + "someFolder/": true, + "somefile": true +} +``` + +And many, many [other customizations](/docs/getstarted/settings.md). + +### Language specific settings + +For those settings you only want for specific languages, you can scope the settings by the language identifier. You can find a list of commonly used language ids in the [Language Identifiers](/docs/languages/identifiers.md) reference. + +```json +"[languageid]": { + +} +``` + +> **Tip:** You can also create language specific settings with the **Configure Language Specific Settings** command. + +![language based settings](images/tips-and-tricks/lang-based-settings.png) + +### Add JSON validation + +Enabled by default for many file types. Create your own schema and validation in `settings.json` + +```json +"json.schemas": [ + { + "fileMatch": [ + "/bower.json" + ], + "url": "http://json.schemastore.org/bower" + } +] +``` + +or for a schema defined in your workspace + +```json +"json.schemas": [ + { + "fileMatch": [ + "/foo.json" + ], + "url": "./myschema.json" + } +] +``` + +or a custom schema + +```json +"json.schemas": [ + { + "fileMatch": [ + "/.myconfig" + ], + "schema": { + "type": "object", + "properties": { + "name" : { + "type": "string", + "description": "The name of the entry" + } + } + } + }, +``` + +See more in the [JSON](/docs/languages/json.md) documentation. + +## Extensions + +Keyboard Shortcut: `kb(workbench.view.extensions)` + +### Find extensions + +1. In the VS Code [Marketplace](https://marketplace.visualstudio.com/vscode). +2. Search inside VS Code in the **Extensions** view. +3. View extension recommendations +4. Community curated extension lists, such as [awesome-vscode](https://github.com/viatsko/awesome-vscode). + +### Install extensions + +In the **Extensions** view, you can search via the search bar or click the **More Actions** (...) button to filter and sort by install count. + +![install extensions](images/tips-and-tricks/InstallExtensions.gif) + +### Extension recommendations + +In the **Extensions** view, click **Show Recommended Extensions** in the **More Actions** (...) button menu. + +![show recommended extensions](images/tips-and-tricks/show-recommended-extensions.png) + +### Creating my own extension + +Are you interested in creating your own extension? You can learn how to do this in the [Extension API documentation](/api), specifically check out the [documentation on contribution points](/api/references/contribution-points.md). + +* configuration +* commands +* keybindings +* languages +* debuggers +* grammars +* themes +* snippets +* jsonValidation + +## Files and folders + +### Integrated Terminal + +Keyboard Shortcut: `kb(workbench.action.terminal.toggleTerminal)` + +![Integrated terminal](images/tips-and-tricks/integrated_terminal.png) + +Further reading: + +* [Integrated Terminal](/docs/editor/integrated-terminal.md) documentation +* [Mastering VS Code's Terminal article](https://www.growingwiththeweb.com/2017/03/mastering-vscodes-terminal.html) + +### Auto Save + +Open User Settings `settings.json` with `kb(workbench.action.openSettings)` + +```json +"files.autoSave": "afterDelay" +``` + +You can also toggle Auto Save from the top-level menu with the **File** > **Auto Save**. + +### Toggle Sidebar + +Keyboard Shortcut: `kb(workbench.action.toggleSidebarVisibility)` + +![toggle side bar](images/tips-and-tricks/toggle_side_bar.gif) + +### Zen mode + +Keyboard Shortcut: `kb(workbench.action.toggleZenMode)` + +![zen mode](images/tips-and-tricks/zen_mode.gif) + +Enter distraction free Zen mode. + +Press `kbstyle(Esc)` twice to exit Zen Mode. + +### Side by side editing + +Keyboard Shortcut: `kb(workbench.action.splitEditor)` + +You can also drag and drop editors to create new editor groups and move editors between groups. + +![split editors](images/tips-and-tricks/split_editor.gif) + +### Switch between editors + +Keyboard Shortcut: `kb(workbench.action.focusFirstEditorGroup)`, `kb(workbench.action.focusSecondEditorGroup)`, `kb(workbench.action.focusThirdEditorGroup)` + +![navigate editors](images/tips-and-tricks/navigate_editors.gif) + +### Move to Explorer window + +Keyboard Shortcut: `kb(workbench.view.explorer)` + +### Create or open a file + +Keyboard Shortcut: `kbstyle(Ctrl+click)` (`kbstyle(Cmd+click)` on macOS) + +You can quickly open a file or image or create a new file by moving the cursor to the file link and using `kbstyle(Ctrl+click)`. + +![create and open file](images/tips-and-tricks/create_open_file.gif) + +### Close the currently opened folder + +Keyboard Shortcut: `kb(workbench.action.closeActiveEditor)` + +### Navigation history + +Navigate entire history: `kb(workbench.action.openNextRecentlyUsedEditorInGroup)` + +Navigate back: `kb(workbench.action.navigateBack)` + +Navigate forward: `kb(workbench.action.navigateForward)` + +![navigate history](images/tips-and-tricks/navigate_history.gif) + +### File associations + +Create language associations for files that aren't detected correctly. For example, many configuration files with custom file extensions are actually JSON. + +```json +"files.associations": { + ".database": "json" +} +``` + +### Preventing dirty writes + +VS Code will show you an error message when you try to save a file that cannot be saved because it has changed on disk. VS Code blocks saving the file to prevent overwriting changes that have been made outside of the editor. + +In order to resolve the save conflict, click the **Compare** action in the error message to open a diff editor that will show you the contents of the file on disk (to the left) compared to the contents in VS Code (on the right): + +![dirty write](images/tips-and-tricks/dirty-write.png) + +Use the actions in the editor toolbar to resolve the save conflict. You can either **Accept** your changes and thereby overwriting any changes on disk, or **Revert** to the version on disk. Reverting means that your changes will be lost. + +**Note:** The file will remain dirty and cannot be saved until you pick one of the two actions to resolve the conflict. + +## Editing hacks + +Here is a selection of common features for editing code. If the keyboard shortcuts aren't comfortable for you, consider installing a [keymap extension](https://marketplace.visualstudio.com/search?target=VSCode&category=Keymaps&sortBy=Downloads) for your old editor. + +**Tip**: You can see recommended keymap extensions in the **Extensions** view with `kb(workbench.extensions.action.showRecommendedKeymapExtensions)` which filters the search to `@recommended:keymaps`. + +### Multi cursor selection + +To add cursors at arbitrary positions, select a position with your mouse and use `kbstyle(Alt+Click)` (`kbstyle(Option+click)` on macOS). + +To set cursors above or below the current position use: + +Keyboard Shortcut: `kb(editor.action.insertCursorAbove)` or `kb(editor.action.insertCursorBelow)` + +![multi cursor](images/tips-and-tricks/multicursor.gif) + +You can add additional cursors to all occurrences of the current selection with `kb(editor.action.selectHighlights)`. + +![add cursor to all occurrences of current selection](images/tips-and-tricks/add_cursor_current_selection.gif) + +> Note: You can also change the modifier to `kbstyle(Ctrl/Cmd)` for applying multiple cursors with the `editor.multiCursorModifier` [setting](/docs/getstarted/settings.md) . See [Multi-cursor Modifier](/docs/editor/codebasics.md#multicursor-modifier) for details. + +If you do not want to add all occurrences of the current selection, you can use `kb(editor.action.addSelectionToNextFindMatch)` instead. +This only selects the next occurrence after the one you selected so you can add selections one by one. + +![add cursor to the next occurrences of current selection one by one](images/tips-and-tricks/add_cursor_current_selection_one_by_one.gif) + +### Column (box) selection + +You can select blocks of text by holding `kbstyle(Shift+Alt)` (`kbstyle(Shift+Option)` on macOS) while you drag your mouse. A separate cursor will be added to the end of each selected line. + +![Column text selection](images/tips-and-tricks/column-select.gif) + +You can also use [keyboard shortcuts](/docs/editor/codebasics.md#column-box-selection) to trigger column selection. + +### Fast scrolling + +Pressing the `kbstyle(Alt)` key enables fast scrolling in the editor and Explorers. By default, fast scrolling uses a 5X speed multiplier but you can control the multiplier with the **Editor: Fast Scroll Sensitivity** (`editor.fastScrollSensitivity`) setting. + +### Copy line up / down + +Keyboard Shortcut: `kb(editor.action.copyLinesUpAction)` or `kb(editor.action.copyLinesDownAction)` + +> The commands **Copy Line Up/Down** are unbound on Linux because the VS Code default keybindings would conflict with Ubuntu keybindings, see [Issue #509](https://github.com/Microsoft/vscode/issues/509). You can still set the commands `editor.action.copyLinesUpAction` and `editor.action.copyLinesDownAction` to your own preferred keyboard shortcuts. + +![copy line down](images/tips-and-tricks/copy_line_down.gif) + +### Move line up and down + +Keyboard Shortcut: `kb(editor.action.moveLinesUpAction)` or `kb(editor.action.moveLinesDownAction)` + +![move line up and down](images/tips-and-tricks/move_line.gif) + +### Shrink / expand selection + +Keyboard Shortcut: `kb(editor.action.smartSelect.shrink)` or `kb(editor.action.smartSelect.expand)` + +![shrink expand selection](images/tips-and-tricks/shrink_expand_selection.gif) + +You can learn more in the [Basic Editing](/docs/editor/codebasics.md#shrinkexpand-selection) documentation. + +### Go to Symbol in File + +Keyboard Shortcut: `kb(workbench.action.gotoSymbol)` + +![Find by symbol](images/tips-and-tricks/find_by_symbol.gif) + +You can group the symbols by kind by adding a colon, `@:`. + +![group symbols by kind](images/tips-and-tricks/group_symbols_by_kind.png) + +### Go to Symbol in Workspace + +Keyboard Shortcut: `kb(workbench.action.showAllSymbols)` + +![go to symbol in workspace](images/tips-and-tricks/go_to_symbol_in_workspace.png) + +### Navigate to a specific line + +Keyboard Shortcut: `kb(workbench.action.gotoLine)` + +### Undo cursor position + +Keyboard Shortcut: `kb(cursorUndo)` + +### Trim trailing whitespace + +Keyboard Shortcut: `kb(editor.action.trimTrailingWhitespace)` + +![trailing whitespace](images/tips-and-tricks/trim_whitespace.gif) + +### Code formatting + +Currently selected source code: `kb(editor.action.formatSelection)` + +Whole document format: `kb(editor.action.formatDocument)` + +![code formatting](images/tips-and-tricks/code_formatting.gif) + +### Code folding + +Keyboard Shortcut: `kb(editor.fold)` and `kb(editor.unfold)` + +![code folding](images/tips-and-tricks/code_folding.gif) + +### Select current line + +Keyboard Shortcut: `kb(expandLineSelection)` + +### Navigate to beginning and end of file + +Keyboard Shortcut: `kb(cursorTop)` and `kb(cursorBottom)` + +### Open Markdown preview + +In a Markdown file, use + +Keyboard Shortcut: `kb(markdown.showPreview)` + +![Markdown preview](images/tips-and-tricks/markdown-preview.png) + +### Side by side Markdown edit and preview + +In a Markdown file, use + +Keyboard Shortcut: `kb(markdown.showPreviewToSide)` + +The preview and editor will synchronize with your scrolling in either view. + +![side by side Markdown preview](images/tips-and-tricks/markdown-preview-side-by-side.png) + +## IntelliSense + +`kb(editor.action.triggerSuggest)` to trigger the Suggestions widget. + +![intellisense](images/tips-and-tricks/intellisense.gif) + +You can view available methods, parameter hints, short documentation, etc. + +### Peek + +Select a symbol then type `kb(editor.action.peekDefinition)`. Alternatively, you can use the context menu. + +![peek](images/tips-and-tricks/peek.gif) + +### Go to Definition + +Select a symbol then type `kb(editor.action.revealDefinition)`. Alternatively, you can use the context menu or `kbstyle(Ctrl+click)` (`kbstyle(Cmd+click)` on macOS). + +![go to definition](images/tips-and-tricks/goto_definition.gif) + +You can go back to your previous location with the **Go** > **Back** command or `kb(workbench.action.navigateBack)`. + +You can also see the type definition if you press `kbstyle(Ctrl)` (`kbstyle(Cmd)` on macOS) when you are hovering over the type. + +### Peek References + +Select a symbol then type `kb(editor.action.referenceSearch.trigger)`. Alternatively, you can use the context menu. + +![peek references](images/tips-and-tricks/find_all_references.gif) + +### Find All References view + +Select a symbol then type `kb(references-view.find)` to open the References view showing all your file's symbols in a dedicated view. + +### Rename Symbol + +Select a symbol then type `kb(editor.action.rename)`. Alternatively, you can use the context menu. + +![rename symbol](images/tips-and-tricks/rename_symbol.gif) + +### Search and modify + +Besides searching and replacing expressions, you can also search and reuse parts of what was matched, using regular expressions with capturing groups. Enable regular expressions in the search box by clicking the **Use Regular Expression** `.*` button (`kb(toggleSearchRegex)`) and then write a regular expression and use parenthesis to define groups. You can then reuse the content matched in each group by using `$1`, `$2`, etc. in the Replace field. + +![search and modify](images/tips-and-tricks/search_and_modify.png) + +### .eslintrc.json + +Install the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint). Configure +your linter however you'd like. Consult the [ESLint specification](https://eslint.org/docs/user-guide/configuring) for details on its linting rules and options. + +Here is configuration to use ES6. + +```json +{ + "env": { + "browser": true, + "commonjs": true, + "es6": true, + "node": true + }, + "parserOptions": { + "ecmaVersion": 6, + "sourceType": "module", + "ecmaFeatures": { + "jsx": true, + "classes": true, + "defaultParams": true + } + }, + "rules": { + "no-const-assign": 1, + "no-extra-semi": 0, + "semi": 0, + "no-fallthrough": 0, + "no-empty": 0, + "no-mixed-spaces-and-tabs": 0, + "no-redeclare": 0, + "no-this-before-super": 1, + "no-undef": 1, + "no-unreachable": 1, + "no-use-before-define": 0, + "constructor-super": 1, + "curly": 0, + "eqeqeq": 0, + "func-names": 0, + "valid-typeof": 1 + } +} +``` + +### package.json + +See IntelliSense for your `package.json` file. + +![package json intellisense](images/tips-and-tricks/package_json_intellisense.gif) + +### Emmet syntax + +[Support for Emmet syntax](/docs/editor/emmet.md). + +![emmet syntax](images/tips-and-tricks/emmet_syntax.gif) + +## Snippets + +### Create custom snippets + +**File** > **Preferences** > **User Snippets** (**Code** > **Preferences** > **User Snippets** on macOS), select the language, and create a snippet. + +```json +"create component": { + "prefix": "component", + "body": [ + "class $1 extends React.Component {", + "", + "\trender() {", + "\t\treturn ($2);", + "\t}", + "", + "}" + ] +}, +``` + +See more details in [Creating your own Snippets](/docs/editor/userdefinedsnippets.md). + +## Git integration + +Keyboard Shortcut: `kb(workbench.view.scm)` + +Git integration comes with VS Code "out-of-the-box". You can install other SCM providers from the extension Marketplace. This section describes the Git integration but much of the UI and gestures are shared by other SCM providers. + +### Diffs + +From the **Source Control** view, select the file to diff. + +![git icon](images/tips-and-tricks/source-control-icon.png) + +**Side by side** + +Default is side by side diff. + +![git diff side by side](images/tips-and-tricks/git_side_by_side.png) + +**Inline view** + +Toggle inline view by clicking the **More Actions** (...) button in the top right and selecting **Switch to Inline View**. + +![git inline](images/tips-and-tricks/git_inline.png) + +If you prefer the inline view, you can set `"diffEditor.renderSideBySide": false`. + +**Review pane** + +Navigate through diffs with `kb(editor.action.diffReview.next)` and `kb(editor.action.diffReview.prev)`. This will present them in a unified patch format. +Lines can be navigated with arrow keys and pressing `kbstyle(Enter)` will jump back in the diff editor and the selected line. + +![diff_review_pane](images/tips-and-tricks/diff_review_pane.png) + +**Edit pending changes** + +You can make edits directly in the pending changes of the diff view. + +### Branches + +Easily switch between Git branches via the Status Bar. + +![switch branches](images/tips-and-tricks/switch_branches.gif) + +### Staging + +**Stage all** + +Hover over the number of files and click the plus button. + +![git stage all](images/tips-and-tricks/git_stage_all.gif) + +**Stage selected** + +Stage a portion of a file by selecting that file (using the arrows) and then choosing **Stage Selected Ranges** from the **Command Palette**. + +### Undo last commit + +![undo last commit](images/tips-and-tricks/undo_last_commit.gif) + +### See Git output + +VS Code makes it easy to see what Git commands are actually running. This is helpful when learning Git or debugging a difficult source control issue. + +Use the **Toggle Output** command (`kb(workbench.action.output.toggleOutput)`) and select **Git** in the drop-down. + +### Gutter indicators + +View diff decorations in editor. See [documentation](/docs/editor/versioncontrol.md#gutter-indicators) for more details. + +![git gutter indicators](images/tips-and-tricks/editingevolved_gutter.png) + +### Resolve merge conflicts + +During a merge, go to the **Source Control** view (`kb(workbench.view.scm)`) and make changes in the diff view. + +### Set VS Code as default merge tool + +```bash +git config --global merge.tool code +``` + +## Debugging + +### Configure debugger + +Open the **Command Palette** (`kb(workbench.action.showCommands)`) and select **Debug: Open launch.json**, which will prompt you to select the environment that matches your project (Node.js, Python, C++, etc). This will generate a `launch.json` file. Node.js support is built-in and other environments require installing the appropriate language extensions. See the debugging [documentation](/docs/editor/debugging.md) for more details. + +![configure debugging](images/tips-and-tricks/configure_debug.gif) + +### Breakpoints and stepping through + +Place breakpoints next to the line number. Navigate forward with the Debug widget. + +![debug](images/tips-and-tricks/node_debug.gif) + +### Data inspection + +Inspect variables in the **Debug** panels and in the console. + +![data inspection](images/tips-and-tricks/debug_data_inspection.gif) + +### Inline values + +You can set `"debug.inlineValues": true` to see variable values inline in the debugger. This feature can be expensive and may slow down stepping, so it is disabled by default. + +## Task runner + +### Auto detect tasks + +Select **Terminal** from the top-level menu, run the command **Configure Tasks**, then select the type of task you'd like to run. +This will generate a `tasks.json` file with content like the following. See the [Tasks](/docs/editor/tasks.md) documentation for more details. + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "type": "npm", + "script": "install", + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} +``` + +There are occasionally issues with auto generation. Check out the documentation for getting things to work properly. + +### Run tasks from the Terminal menu + +Select **Terminal** from the top-level menu, run the command **Run Task**, and select the task you want to run. Terminate the running task by running the command **Terminate Task** + +![task runner](images/tips-and-tricks/task_runner.gif) + +### Define keyboard shortcuts for tasks + +You can define a keyboard shortcut for any task. From the **Command Palette** (`kb(workbench.action.showCommands)`), select **Preferences: Open Keyboard Shortcuts File**, bind the desired shortcut to the `workbench.action.tasks.runTask` command, and define the **Task** as `args`. + +For example, to bind `kbstyle(Ctrl+H)` to the `Run tests` task, add the following: + +```json +{ + "key": "ctrl+h", + "command": "workbench.action.tasks.runTask", + "args": "Run tests" +} +``` + +### Run npm scripts as tasks from the explorer + +With the setting `npm.enableScriptExplorer`, you can enable an explorer that shows the scripts defined in your workspace. + +![Filter problems](images/tips-and-tricks/script_explorer.png) + +From the explorer you can open a script in the editor, run it as a task, and launch it with the node debugger (when the script defines a debug option like `--inspect-brk`). The default action on click is to open the script. To run a script on a single click, set `npm.scriptExplorerAction` to "run". Use the setting `npm.exclude` to exclude scripts in `package.json` files contained in particular folders. + +## Portable mode + +VS Code has a [Portable mode](/docs/editor/portable.md) which lets you keep settings and data in the same location as your installation, for example, on a USB drive. + +## Insiders builds + +The Visual Studio Code team uses the Insiders version to test the latest features and bug fixes of VS Code. You can also use the Insiders version by [downloading it here](/insiders). + +* For Early Adopters - Insiders has the most recent code changes for users and extension authors to try out. +* Frequent Builds - New builds every day with the latest bug fixes and features. +* Side-by-side install - Insiders installs next to the Stable build allowing you to use either independently. diff --git a/docs/getstarted/userinterface.md b/docs/getstarted/userinterface.md new file mode 100644 index 0000000000000000000000000000000000000000..120ee160ce096337aabbbb3554f381bd9f0059c0 --- /dev/null +++ b/docs/getstarted/userinterface.md @@ -0,0 +1,374 @@ +--- +Order: 4 +Area: getstarted +TOCTitle: User Interface +ContentId: 3a33f35b-cded-4f7f-8674-6f2ba5fca023 +PageTitle: Visual Studio Code User Interface +DateApproved: 3/7/2019 +MetaDescription: A quick overview of the Visual Studio Code user interface. Learn about the editor, window management, and special UI to handle source control, extension management, full text search and more. +--- +# User Interface + +At its heart, Visual Studio Code is a code editor. Like many other code editors, VS Code adopts a common user interface and layout of an explorer on the left, showing all of the files and folders you have access to, and an editor on the right, showing the content of the files you have opened. + +![code basics hero](images/userinterface/hero.png) + +## Basic Layout + +VS Code comes with a simple and intuitive layout that maximizes the space provided for the editor while leaving ample room to browse and access the full context of your folder or project. The UI is divided into five areas: + +* **Editor** - The main area to edit your files. You can open as many editors as you like side by side vertically and horizontally. +* **Side Bar** - Contains different views like the Explorer to assist you while working on your project. +* **Status Bar** - Information about the opened project and the files you edit. +* **Activity Bar** - Located on the far left-hand side, this lets you switch between views and gives you additional context-specific indicators, like the number of outgoing changes when Git is enabled. +* **Panels** - You can display different panels below the editor region for output or debug information, errors and warnings, or an integrated terminal. Panel can also be moved to the right for more vertical space. + +Each time you start VS Code, it opens up in the same state it was in when you last closed it. The folder, layout, and opened files are preserved. + +Open files in each editor are displayed with tabbed headers (Tabs) at the top of the editor region. To learn more about tabbed headers, see the [Tabs](/docs/getstarted/userinterface.md#tabs) section below. + +>**Tip:** You can move the Side Bar to the right hand side (**View** > **Move Side Bar Right**) or toggle its visibility (`kb(workbench.action.toggleSidebarVisibility)`). + +## Side by side editing + +You can open as many editors as you like side by side vertically and horizontally. If you already have one editor open, there are multiple ways of opening another editor to the side of the existing one: + +* `kbstyle(Alt)` click on a file in the Explorer. +* `kb(workbench.action.splitEditor)` to split the active editor into two. +* **Open to the Side** (`kb(explorer.openToSide)`) from the Explorer context menu on a file. +* Click the **Split Editor** button in the upper right of an editor. +* Drag and drop a file to any side of the editor region. +* `kbstyle(Ctrl+Enter)` (macOS: `kbstyle(Cmd+Enter)`) in the **Quick Open** (`kb(workbench.action.quickOpen)`) file list. + +![Side by Side editing](images/userinterface/sidebyside.png) + +Whenever you open another file, the editor that is active will display the content of that file. So if you have two editors side by side and you want to open file 'foo.cs' into the right hand editor, make sure that editor is active (by clicking inside it) before opening file 'foo.cs'. + +By default editors will open to the right hand side of the active one. You can change this behavior through the setting `workbench.editor.openSideBySideDirection` and configure to open new editors to the bottom of the active one instead. + +When you have more than one editor open you can switch between them quickly by holding the `kbstyle(Ctrl)` (macOS: `kbstyle(Cmd)`) key and pressing `kbstyle(1)`, `kbstyle(2)`, or `kbstyle(3)`. + +>**Tip:** You can resize editors and reorder them. Drag and drop the editor title area to reposition or resize the editor. + +## Minimap + +A Minimap (code outline) gives you a high level overview of your source code which is very useful for quick navigation and code understanding. A file's minimap is shown in the right side of the editor. You can click or drag the shaded area to quickly jump to different sections of your file. + +![minimap](images/userinterface/minimap.png) + +>**Tip:** You can move the minimap to the left hand side or disable it completely by respectively setting `"editor.minimap.side": "left"` or `"editor.minimap.enabled": false` in your user or workspace [settings](/docs/getstarted/settings.md). + +### Indent Guides + +The image above also shows indentation guides (vertical lines) which help you quickly see matching indent levels. If you would like to disable indent guides, you can set `"editor.renderIndentGuides": false` in your user or workspace [settings](/docs/getstarted/settings.md). + +## Explorer + +The Explorer is used to browse, open, and manage all of the files and folders in your project. VS Code is file and folder based - you can get started immediately by opening a file or folder in VS Code. + +After opening a folder in VS Code, the contents of the folder are shown in the Explorer. You can do many things from here: + +* Create, delete, and rename files and folders. +* Move files and folders with drag and drop. +* Use the context menu to explore all options. + +>**Tip:** You can drag and drop files into the Explorer from outside VS Code to copy them (if the explorer is empty VS Code will open them instead) + +![Explorer Menu](images/userinterface/explorer_menu.png) + +VS Code works very well with other tools that you might use, especially command-line tools. If you want to run a command-line tool in the context of the folder you currently have open in VS Code, right-click the folder and select **Open in Command Prompt** (or **Open in Terminal** on macOS or Linux). + +You can also navigate to the location of a file or folder in the native Explorer by right-clicking on a file or folder and selecting **Reveal in Explorer** (or **Reveal in Finder** on the macOS or **Open Containing Folder** on Linux). + +>**Tip:** Type `kb(workbench.action.quickOpen)` (**Quick Open**) to quickly search and open a file by its name. + +By default, VS Code excludes some folders from the Explorer (for example. `.git`). Use the `files.exclude` [setting](/docs/getstarted/settings.md) to configure rules for hiding files and folders from the Explorer. + +>**Tip:** This is really useful to hide derived resources files, like `\*.meta` in Unity, or `\*.js` in a TypeScript project. For Unity to exclude the `\*.cs.meta` files, the pattern to choose would be: `"**/*.cs.meta": true`. For TypeScript, you can exclude generated JavaScript for TypeScript files with: `"**/*.js": {"when": "$(basename).ts"}`. + +### Multi-selection + +You can select multiple files in the **File Explorer** and **OPEN EDITORS** view to run actions (Delete, Drag and Drop, Open to the Side) on multiple items. Use the `Ctrl/Cmd` key with `click` to select individual files and `Shift` + `click` to select a range. If you select two items, you can now use the **Compare Selected** command to quickly diff two files. + +**Note:** In earlier VS Code releases, clicking with the `Ctrl/Cmd` key pressed would open a file in a new Editor Group to the side. If you would still like this behavior, you can use the `workbench.list.multiSelectModifier` setting to change multi-selection to use the `Alt` key. + +```json +"workbench.list.multiSelectModifier": "alt" +``` + +### Outline view + +The Outline view is a separate section in the bottom of the File Explorer. When expanded, it will show the symbol tree of the currently active editor. + +![Outline view](images/userinterface/outline-view.png) + +The Outline view has different **Sort By** modes, optional cursor tracking, and supports the usual open gestures. It also includes an input box which finds or filters symbols as you type. Errors and warnings are also shown in the Outline view, letting you see at a glance a problem's location. + +For symbols, the view relies on information computed by your installed extensions for different file types. For example, the built-in Markdown support returns the Markdown header hierarchy for a Markdown file's symbols. + +![Markdown Outline view](images/userinterface/markdown-outline-view.png) + +There are several Outline view [settings](/docs/getstarted/settings.md) which allow you to enable/disable icons and control the errors and warnings display (all enabled by default): + +* `outline.icons` - Toggle rendering outline elements with icons. +* `outline.problems.enabled` - Show errors and warnings on outline elements. +* `outline.problems.badges` - Toggle using badges for errors and warnings. +* `outline.problems.colors` - Toggle using colors for errors and warnings. + +## Open Editors + +At the top of the Explorer is a view labeled **OPEN EDITORS**. This is a list of active files or previews. These are files you previously opened in VS Code that you're working on. For example, a file will be listed in the **OPEN EDITORS** view if you: + +* Make a change to a file. +* Double-click a file's header. +* Double-click a file in the Explorer. +* Open a file that is not part of the current folder. + +Just click an item in the **OPEN EDITORS** view, and it becomes active in VS Code. + +Once you are done with your task, you can remove files individually from the **OPEN EDITORS** view, or you can remove all files by using the **View: Close All Editors** or **View: Close All Editors in Group** actions. + +## Views + +The File Explorer is just one of the Views available in VS Code. There are also Views for: + +* **Search** - Provides global search and replace across your open folder. +* **Source Control** - VS Code includes Git source control by default. +* **Debug** - VS Code's Debug View displays variables, call stacks, and breakpoints. +* **Extensions** - Install and manage your extensions within VS Code. +* **Custom views** - Views contributed by extensions under Explorer and Debug views. + +> **Tip:** You can open any view using the **View: Open View** command. + +![views](images/userinterface/views.png) + +You can show or hide views from within the main view and also reorder them by drag and drop. + +![view management](images/userinterface/view-management.png) + +### Activity Bar + +The **Activity Bar** on the left lets you quickly switch between Views. You can also reorder Views by dragging and dropping them on the **Activity Bar** or remove a View entirely (right click **Hide from Activity Bar**). + +![activity bar context menu](images/userinterface/activity-bar-context-menu.png) + +## Command Palette + +VS Code is equally accessible from the keyboard. The most important key combination to know is `kb(workbench.action.showCommands)`, which brings up the **Command Palette**. From here, you have access to all of the functionality of VS Code, including keyboard shortcuts for the most common operations. + +![Command Palette](images/userinterface/commands.png) + +The **Command Palette** provides access to many commands. You can execute editor commands, open files, search for symbols, and see a quick outline of a file, all using the same interactive window. Here are a few tips: + +* `kb(workbench.action.quickOpen)` will let you navigate to any file or symbol by typing its name +* `kb(workbench.action.openPreviousRecentlyUsedEditorInGroup)` will cycle you through the last set of files opened +* `kb(workbench.action.showCommands)` will bring you directly to the editor commands +* `kb(workbench.action.gotoSymbol)` will let you navigate to a specific symbol in a file +* `kb(workbench.action.gotoLine)` will let you navigate to a specific line in a file + +Type `?` into the input field to get a list of available commands you can execute from here: + +![Quick Open Help](images/userinterface/quickopenhelp.png) + +## Configuring the editor + +VS Code gives you many options to configure the editor. From the **View** menu, you can hide or toggle various parts of the user interface, such as the **Side Bar**, **Status Bar**, and **Activity Bar**. + +### Hide the Menu Bar (Windows, Linux) + +You can hide the Menu Bar on Windows and Linux with the **View** > **Toggle Menu Bar** command. You can still access the Menu Bar by pressing the `kbstyle(Alt)` key (`window.menuBarVisibility` setting). + +### Settings + +Most editor configurations are kept in settings which can be modified directly. You can set options globally through user settings or per project/folder through workspace settings. Settings values are kept in a `settings.json` [file](/docs/getstarted/settings.md#settings-file-locations). + +* Select **File** > **Preferences** > **Settings** (or press `kb(workbench.action.openSettings)`) to edit the user `settings.json` file. +* To edit workspace settings, select the **WORKSPACE SETTINGS** tab to edit the workspace `settings.json` file. + +>**Note for macOS users:** The **Preferences** menu is under **Code** not **File**. For example, **Code** > **Preferences** > **Settings**. + +![workspace settings](images/userinterface/workspace-settings.png) + +You will see the VS Code [Default Settings](/docs/getstarted/settings.md#default-settings) in the left window and your editable `settings.json` on the right. You can easily filter settings in the `Default Settings` using the search box at the top. Copy a setting over to the editable `settings.json` on the right by clicking on the edit icon to the left of the setting. Settings with a fixed set of values allow you to pick a value as part of their edit icon menu. + +After editing your settings, type `kb(workbench.action.files.save)` to save your changes. The changes will take effect immediately. + +>**Note:** Workspace settings will override User settings and are useful for sharing project specific settings across a team. + +### Zen Mode + +Zen Mode lets you focus on your code by hiding all UI except the editor (no Activity Bar, Status Bar, Side Bar and Panel), going to full screen and centering the editor layout. Zen mode can be toggled using **View** menu, **Command Palette** or by the shortcut `kb(workbench.action.toggleZenMode)`. Double `kbstyle(Esc)` exits Zen Mode. The transition to full screen can be disabled via `zenMode.fullScreen`. Zen Mode can be further tuned by the following settings: `zenMode.hideStatusBar`, `zenMode.hideTabs`, `zenMode.fullScreen`, `zenMode.restore` and `zenMode.centerLayout`. + +### Centered editor layout + +Centered editor layout allows you to center the editor area. This is particularly useful when working with a single editor on a large monitor. You can use the sashes on the side to resize the view (hold down the `Alt` key to independently move the sashes). + +## Tabs + +Visual Studio Code shows open items with Tabs (tabbed headings) in the title area above the editor. + +When you open a file, a new Tab is added for that file. + +![tabs hero](images/userinterface/tabs-hero.png) + +Tabs let you quickly navigate between items and you can Drag and Drop Tabs to reorder them. + +When you have more open items than can fit in the title area, you can use the **Show Opened Editors** command (available through the `...` More button) to display a drop-down list of tabbed items. + +If you don't want to use Tabs, you can disable the feature by setting the `workbench.editor.showTabs` [setting](/docs/getstarted/settings.md) to false: + +```json + "workbench.editor.showTabs": false +``` + +See the section below to optimize VS Code when [working without Tabs](/docs/getstarted/userinterface.md#working-without-tabs). + +### Tab ordering + +By default, new Tabs are added to the right of the existing Tabs but you can control where you'd like new Tabs to appear with the `workbench.editor.openPositioning` setting. + +For example, you might like new tabbed items to appear on the left: + +```json + "workbench.editor.openPositioning": "left" +``` + +## Preview mode + +When you single-click or select a file in the Explorer, it is shown in a preview mode and reuses an existing Tab. This is useful if you are quickly browsing files and don't want every visited file to have its own Tab. When you start editing the file or use double-click to open the file from the Explorer, a new Tab is dedicated to that file. + +Preview mode is indicated by italics in the Tab heading: + +![preview mode](images/userinterface/preview-tab.png) + +If you'd prefer to not use preview mode and always create a new Tab, you can control the behavior with these settings: + +* `workbench.editor.enablePreview` to globally enable or disable preview editors +* `workbench.editor.enablePreviewFromQuickOpen` to enable or disable preview editors when opened from **Quick Open** + +## Editor Groups + +When you split an editor (using the **Split Editor** or **Open to the Side** commands), a new editor region is created which can hold a group of items. You can open as many editor regions as you like side by side vertically and horizontally. + +You can see these clearly in the **OPEN EDITORS** section at the top of the Explorer view: + +![tabs editor groups](images/userinterface/tabs-editor-groups.png) + +You can Drag and Drop editor groups on the workbench, move individual Tabs between groups and quickly close entire groups (**Close All**). + +>**Note:** VS Code uses editor groups whether or not you have enabled Tabs. Without Tabs, editor groups are a stack of your open items with the most recently selected item visible in the editor pane. + +## Grid editor layout + +By default, editor groups are laid out in vertical columns (e.g. when you split an editor to open it to the side). You can easily arrange editor groups in any layout you like, both vertically and horizontally: + +![Grid Editor Layout](images/userinterface/grid-layout.gif) + +To support flexible layouts, you can create empty editor groups. By default, closing the last editor of an editor group will also close the group itself, but you can change this behavior with the new setting `workbench.editor.closeEmptyGroups: false`: + +![Grid Empty](images/userinterface/grid-empty.png) + +There are a predefined set of editor layouts in the new **View** > **Editor Layout** menu: + +![Grid Editor Layout Menu](images/userinterface/grid-layout-menu.png) + +Editors that open to the side (for example by clicking the editor toolbar **Split Editor** action) will by default open to the right hand side of the active editor. If you prefer to open editors below the active one, configure the new setting `workbench.editor.openSideBySideDirection: down`. + +There are many keyboard commands for adjusting the editor layout with the keyboard alone, but if you prefer to use the mouse, drag and drop is a fast way to split the editor into any direction: + +![Grid Editor Drag and Drop](images/userinterface/grid-dnd.gif) + +>**Pro Tip**: If you press and hold the `Alt` key while hovering over the toolbar action to split an editor, it will offer to split to the other orientation. This is a fast way to split either to the right or to the bottom. + +![Grid Alt Click](images/userinterface/grid-alt.gif) + +### Keyboard shortcuts + +Here are some handy keyboard shortcuts to quickly navigate between editors and editor groups. + +>If you'd like to modify the default keyboard shortcuts, see [Key Bindings](/docs/getstarted/keybindings.md) for details. + +* `kb(workbench.action.nextEditor)` go to the right editor. +* `kb(workbench.action.previousEditor)` go to the left editor. +* `kb(workbench.action.openNextRecentlyUsedEditorInGroup)` open the next editor in the editor group MRU list. +* `kb(workbench.action.openPreviousRecentlyUsedEditorInGroup)` open the previous editor in the editor group MRU list. +* `kb(workbench.action.focusFirstEditorGroup)` go to the leftmost editor group. +* `kb(workbench.action.focusSecondEditorGroup)` go to the center editor group. +* `kb(workbench.action.focusThirdEditorGroup)` go to the rightmost editor group. +* `kb(workbench.action.focusPreviousGroup)` go to the previous editor group. +* `kb(workbench.action.focusNextGroup)` go to the next editor group. +* `kb(workbench.action.closeActiveEditor)` close the active editor. +* `kb(workbench.action.closeEditorsInGroup)` close all editors in the editor group. +* `kb(workbench.action.closeAllEditors)` close all editors. + +## Working without Tabs + +If you prefer not to use Tabs (tabbed headings), you can disable Tabs (tabbed headings) entirely by setting `workbench.editor.showTabs` to false. + +### Disable Preview mode + +Without Tabs, the **OPEN EDITORS** section of the File Explorer is a quick way to do file navigation. With [preview editor mode](/docs/getstarted/userinterface.md#preview-mode), files are not added to the **OPEN EDITOR** list nor editor group on single-click open. You can disable this feature through the `workbench.editor.enablePreview` and `workbench.editor.enablePreviewFromQuickOpen` settings. + +### Ctrl+Tab to navigate in entire editor history + +You can change keybindings for `kbstyle(Ctrl+Tab)` to show you a list of all opened editors from the history independent from the active editor group. + +Edit your [keybindings](/docs/getstarted/keybindings.md) and add the following: + +```json +{ "key": "ctrl+tab", "command": "workbench.action.openPreviousEditorFromHistory" }, +{ "key": "ctrl+tab", "command": "workbench.action.quickOpenNavigateNext", "when": "inQuickOpen" }, +``` + +### Close an entire group instead of a single editor + +If you liked the behavior of VS Code closing an entire group when closing one editor, you can bind the following in your [keybindings](/docs/getstarted/keybindings.md). + +macOS: + +```json +{ "key": "cmd+w", "command": "workbench.action.closeEditorsInGroup" } +``` + +Windows/Linux: + +```json +{ "key": "ctrl+w", "command": "workbench.action.closeEditorsInGroup" } +``` + +## Window management + +VS Code has some options to control how windows (instances) should be opened or restored between sessions. + +The settings `window.openFoldersInNewWindow` and `window.openFilesInNewWindow` are provided to configure opening new windows or reusing the last active window for files or folders and possible values are `default`, `on` and `off`. + +If configured to be `default`, we will make the best guess about reusing a window or not based on the context from where the open request was made. Flip this to `on` or `off` to always behave the same. For example, if you feel that picking a file or folder from the **File** menu should always open into a new window, set this to `on`. + +Note: There can still be cases where this setting is ignored (for example, when using the `-new-window` or `-reuse-window` command line option). + +The `window.restoreWindows` setting tells VS Code how to restore the opened windows of your previous session. By default, VS Code will +reopen the last opened window you worked on (setting: `one`). Change this setting to `none` to never reopen any windows and always start with an empty VS Code instance. Change it to `all` to restore all windows you worked on during your previous session or `folders` to only restore windows that had folders opened. + +## Next steps + +Now that you know the overall layout of VS Code, start to customize the editor to how you like to work by looking at the following topics: + +* [Changing the Theme](/docs/getstarted/themes.md) - Set a Color and/or File Icon theme to your preference. + +## Common questions + +### How can I change the color of the indent guides? + +The indent guide colors are customizable as are most VS Code UI elements. To [customize](/docs/getstarted/theme-color-reference.md) the indent guides color for your active color theme, use the `workbench.colorCustomizations` [setting](/docs/getstarted/settings.md) and modify the `editorIndentGuide.background` value. + +For example, to make the indent guides bright blue, add the following to your `settings.json`: + +```json +"workbench.colorCustomizations": { + "editorIndentGuide.background": "#0000ff" +} +``` + +### Can I hide the OPEN EDITORS section in the Explorer? + +Yes, you can hide the **OPEN EDITORS** list with the `explorer.openEditors.visible` [setting](/docs/getstarted/settings.md), which declares how many items to display before a scroll bar appears. Setting `"explorer.openEditors.visible": 0` will hide **OPEN EDITORS** when you have an open folder. The list will still be displayed if you are using VS Code to view loose files. diff --git a/docs/introvideos/basics.md b/docs/introvideos/basics.md new file mode 100644 index 0000000000000000000000000000000000000000..9c36bbc874db43ef5b7aa097c73f2d5f94727595 --- /dev/null +++ b/docs/introvideos/basics.md @@ -0,0 +1,35 @@ +--- +Order: +Area: introvideos +TOCTitle: Getting started +ContentId: baf150cd-6daf-4604-87db-a7c70a6706a7 +PageTitle: Getting started with Visual Studio Code +DateApproved: 7/30/2018 +MetaDescription: Download and learn the basics of Visual Studio Code. +MetaSocialImage: images/opengraph/introvideos.png +--- +# Getting started with Visual Studio Code + +In this tutorial, we walk you through setting up Visual Studio Code and give an overview of the basic features. + + + +## Outline + +* Download and install VS Code. +* See an overview of the user interface. +* Install support for your favorite programming language. +* Change your keyboard shortcuts and easily migrate from other editors using keybinding extensions. +* Customize your editor with themes. +* Explore VS Code features in the **Interactive Editor Playground**. + +## Learn More + +* [User Interface](/docs/getstarted/userinterface.md) - View the documentation for VS Code. +* [Setup Overview](/docs/setup/setup-overview.md) - Documentation for getting up and running with VS Code, including platform specific setup. +* [Keyboard Shortcuts](/docs/getstarted/keybindings.md) - Customize your own shortcuts, download a reference sheet, or install a Keymap extension. +* [Keybinding extensions](https://marketplace.visualstudio.com/search?target=VSCode&category=Keymaps&sortBy=Downloads) - Install a Keymap extension to bring the keybindings from your previous editor to VS Code. + +## Next Video + +* [Customize Visual Studio Code](/docs/introvideos/configure.md) - Learn how to personalize VS Code to your work style. \ No newline at end of file diff --git a/docs/introvideos/codeediting.md b/docs/introvideos/codeediting.md new file mode 100644 index 0000000000000000000000000000000000000000..4e26e16ea04fc01c6e65438f34f4fdf6b44e21b1 --- /dev/null +++ b/docs/introvideos/codeediting.md @@ -0,0 +1,43 @@ +--- +Order: +Area: introvideos +TOCTitle: Code Editing +ContentId: 826efeef-6803-49bd-a500-06c6c42cda19 +PageTitle: Code Editing Features in Visual Studio Code +DateApproved: 3/6/2017 +MetaDescription: Take coding to the next level of speed and efficiency with these code editing features. +MetaSocialImage: images/opengraph/introvideos.png +--- +# Code Editing in Visual Studio Code + +In this Visual Studio Code tutorial, we cover source code editing, including the features outlined below. After viewing this overview, read on in the [Learn More](/docs/introvideos/codeediting.md#learn-more) section to see more features. + + + +## Outline + +* Emmet syntax for HTML and CSS development +* Hover over CSS elements +* Use case of using a task +* Global find and replace, including regex search +* ESLint for JavaScript linting +* Errors and Warning output +* Multi-cursor editing +* Code folding +* Bracket matching +* Code formatting to consistently style code + +## Learn More + +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Emmet Snippets](/docs/languages/html.md#emmet-snippets) - Use Emmet Snippets. +* [Tasks](/docs/editor/tasks.md) - Create tasks to use external tools inside VS Code. +* [JavaScript Linters](/docs/languages/javascript.md#javascript-linters) - Install linters for JavaScript. +* [Code Folding](/docs/editor/codebasics.md#folding) - See the details of source code folding. +* [Tips and Tricks](/docs/getstarted/tips-and-tricks.md) - Helpful tips and tricks for VS Code. + +## Next Video + +* [IntelliSense](/docs/introvideos/intellisense.md) - Set up IntelliSense for intelligent code completion. + diff --git a/docs/introvideos/configure.md b/docs/introvideos/configure.md new file mode 100644 index 0000000000000000000000000000000000000000..ff4a48c1505c064ba03dcbe40e132e270fe79e7e --- /dev/null +++ b/docs/introvideos/configure.md @@ -0,0 +1,33 @@ +--- +Order: +Area: introvideos +TOCTitle: Customize +ContentId: d9583ed0-aaf6-4ce1-9a27-bbfb0017b6be +PageTitle: Customize Visual Studio Code +DateApproved: 3/6/2017 +MetaDescription: Learn how to configure Visual Studio Code, including settings, keybindings, and snippets +MetaSocialImage: images/opengraph/introvideos.png +--- +# Customize Visual Studio Code + +In this tutorial, we show you how to personalize Visual Studio Code. + + + +## Outline + +* Change your UI Color Theme and File Icon Theme. +* Find customization options in user and workspace settings. +* Learn and change keyboard shortcuts (key bindings). +* Write code faster with snippets, including creating your own. + +## Learn More + +* [User and Workspace Settings](/docs/getstarted/settings.md) - Configure user and workspace settings. +* [Key Bindings](/docs/getstarted/keybindings.md) - See the default keyboard shortcuts (key bindings) for editing, navigation, and more. +* [Snippets](/docs/editor/userdefinedsnippets.md) - Create your own custom snippets. +* [Themes](/docs/getstarted/themes.md) - Change your Color Theme to customize VS Code's background text and language syntax colorization. + +## Next Video + +* [Extensions in Visual Studio Code](/docs/introvideos/extend.md) - Add features to VS Code through Extensions. diff --git a/docs/introvideos/debugging.md b/docs/introvideos/debugging.md new file mode 100644 index 0000000000000000000000000000000000000000..07b56f4ed55d6ad442ede2fe9f17091a02cff9e2 --- /dev/null +++ b/docs/introvideos/debugging.md @@ -0,0 +1,34 @@ +--- +Order: +Area: introvideos +TOCTitle: Debugging +ContentId: cf275b3d-c1d8-4a55-b2eb-a8a744882b6a +PageTitle: Introduction to Debugging in Visual Studio Code +DateApproved: 7/30/2018 +MetaDescription: Debugging is a core feature of Visual Studio Code. Learn how to configure and use the Node.js debugger in this introductory video. +MetaSocialImage: images/opengraph/introvideos.png +--- +# Debugging in Visual Studio Code + +Debugging is a core feature of Visual Studio Code. In this tutorial, we will show you how to configure and use debugging basics. We will walk you through how you get started with Node.js debugging in VS Code. + +> **Tip:** To use the debugging features demonstrated in this video for Node.js, you will need to first install [Node.js](https://nodejs.org/en/). + + + +## Outline + +* Debugging that "just works". +* Single file debugging. +* Using a `launch.json` configuration files. +* The difference between launch and attach debug configurations. +* Use Watches to inspect your program's state and variables. + +## Learn More + +* [Debugging](/docs/editor/debugging.md) - Official documentation for VS Code debugging. +* [Integrated Terminal](/docs/editor/integrated-terminal.md) - Use the integrated terminal inside VS Code. + +## Next steps + +* [Git Version Control](/docs/introvideos/versioncontrol.md) - Learn the basics of Git version control. diff --git a/docs/introvideos/extend.md b/docs/introvideos/extend.md new file mode 100644 index 0000000000000000000000000000000000000000..c0d7fd840313a6fd444b7c209a3a60a8a5a80208 --- /dev/null +++ b/docs/introvideos/extend.md @@ -0,0 +1,32 @@ +--- +Order: 5 +Area: introvideos +TOCTitle: Extend +ContentId: c720387b-e6db-4b40-865f-0c0a814b0b12 +PageTitle: Extensions in Visual Studio Code +DateApproved: 3/6/2017 +MetaDescription: Use extensions in Visual Studio Code to add new features, themes, and more. +MetaSocialImage: images/opengraph/introvideos.png +--- +# Using Extensions in Visual Studio Code + +Use Visual Studio Code extensions to add new features, themes and more. In this tutorial, we will show you how to find extensions, install the ones you like, and disable extensions you don't want to use all the time. + + + +## Outline + +* Find extensions to install using the Extensions View. +* Install an extension. +* See what features are added via the **Contributions** tab. +* See the list of **Recommended Extensions**. +* Disable and uninstall extensions. + +## Learn More + +* [Extension Marketplace Documentation](/docs/editor/extension-gallery.md) - Official documentation for the VS Code Extension Marketplace. +* [Marketplace](https://marketplace.visualstudio.com/) - Browse extensions online. + +## Next steps + +* [Code Editing in Visual Studio Code](/docs/introvideos/codeediting.md) - Learn about the advanced code editing features in VS Code. diff --git a/docs/introvideos/images/opengraph/introvideos.png b/docs/introvideos/images/opengraph/introvideos.png new file mode 100644 index 0000000000000000000000000000000000000000..ff9229240d77f956409a9991de8c229f0b80d993 --- /dev/null +++ b/docs/introvideos/images/opengraph/introvideos.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7fdd7dac64b889eeb369f3082b115e9ca647c6c73398c9f990faa099d7e40985 +size 160131 diff --git a/docs/introvideos/intellisense.md b/docs/introvideos/intellisense.md new file mode 100644 index 0000000000000000000000000000000000000000..02aef81d9aeb7af32f8ee11c07d363adaecf670d --- /dev/null +++ b/docs/introvideos/intellisense.md @@ -0,0 +1,35 @@ +--- +Order: +Area: introvideos +TOCTitle: IntelliSense +ContentId: 3e36b1fa-cefc-4a07-9773-e672da5881a2 +PageTitle: Learn about IntelliSense in Visual Studio Code +DateApproved: 3/6/2017 +MetaDescription: IntelliSense is a fundamental feature for Visual Studio Code. In this article, learn how to use IntelliSense for JavaScript in VS Code. +MetaSocialImage: images/opengraph/introvideos.png +--- +# IntelliSense in Visual Studio Code + +In this tutorial, we show you how to set up IntelliSense for a JavaScript project. + +> Note: For IntelliSense with other programming languages, consult the language extension's README. You can learn more about language support [here](/docs/languages/overview.md). + + + +## Outline + +* IntelliSense basics +* Parameter Info +* Go To Definition +* JSON IntelliSense +* Enabling IntelliSense for other languages + +## Learn More + +* [JavaScript IntelliSense](/docs/languages/javascript.md#intellisense) - Define a JavaScript project with `jsconfig.json` to get IntelliSense across files. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Node.js Tutorial](/docs/nodejs/nodejs-tutorial.md) - See IntelliSense in action for Node.js. + +## Next Video + +* [Debugging](/docs/introvideos/debugging.md) - Learn how to debug your application, including setting breakpoints and inspecting variables. diff --git a/docs/introvideos/quicktour.md b/docs/introvideos/quicktour.md new file mode 100644 index 0000000000000000000000000000000000000000..2a81a6cfe42613b1aeb18df80c907a10071230c7 --- /dev/null +++ b/docs/introvideos/quicktour.md @@ -0,0 +1,37 @@ +--- +Order: +Area: introvideos +TOCTitle: Quick Tour using JavaScript +ContentId: a51b707c-19f7-41af-b5c2-c296e6e9fea2 +PageTitle: Quick Tour of Visual Studio Code using JavaScript +DateApproved: 3/6/2017 +MetaDescription: Quick Tour around Visual Studio Code using JavaScript. +MetaSocialImage: images/opengraph/introvideos.png +--- + +# Quick Tour of VS Code using JavaScript + +This tutorial gives you an overview of the core features of Visual Studio Code, including IntelliSense, debugging, Git version control integration, and more. You'll see these features as we add an endpoint to a JavaScript web app using [Express web framework](https://expressjs.com/). + + + +## Outline + +* See IntelliSense in action. +* Start and run the debugger. +* Commit source code changes with Git integration. +* Run shell commands in the **Integrated Terminal**. +* Add new features with VS Code extensions. + +## Learn More + +* [IntelliSense](/docs/editor/intellisense.md) - Learn more about IntelliSense and how to use it effectively for your language. +* [JavaScript IntelliSense](/docs/languages/javascript.md#intellisense) - Define a JavaScript project with `jsconfig.json` to get IntelliSense across files. +* [Debugging](/docs/editor/debugging.md) - Official documentation for VS Code debugging. +* [Extension Marketplace](/docs/editor/extension-gallery.md) - Find and install new extensions. +* [Integrated Terminal](/docs/editor/integrated-terminal.md) - Use the Integrated Terminal inside VS Code. + + +## Next Video + +* [Setup and Basics](/docs/introvideos/basics.md) - Install and learn the basics of your new editor. \ No newline at end of file diff --git a/docs/introvideos/versioncontrol.md b/docs/introvideos/versioncontrol.md new file mode 100644 index 0000000000000000000000000000000000000000..bc3f56bcc3002e6d6dd96bf8a3bbe2b8c3b716f2 --- /dev/null +++ b/docs/introvideos/versioncontrol.md @@ -0,0 +1,31 @@ +--- +Order: +Area: introvideos +TOCTitle: Git Version Control +ContentId: 2447F8EB-15F1-4279-B621-126C7B8EBF4B +PageTitle: Git Version Control in Visual Studio Code +DateApproved: 8/5/2016 +MetaDescription: Learn how to use Git version control basics in Visual Studio Code. +MetaSocialImage: images/opengraph/introvideos.png +--- +# Git Version Control in VS Code + +In this tutorial, we will learn how to use the basics of Git version control in Visual Studio Code. + + + +## Outline + +* Create a branch +* Change branches +* View diffs between two files +* Stage and clean changes +* Undo a commit +* Publish to a remote branch +* Push commits +* View git commands in Git output + +## Learn More + +* [Version Control](/docs/editor/versioncontrol.md) - Read more about integrated Git support. +* [Setup Overview](/docs/setup/setup-overview.md) - Set up and start using VS Code. \ No newline at end of file diff --git a/docs/java/extensions.md b/docs/java/extensions.md new file mode 100644 index 0000000000000000000000000000000000000000..7ff6418bb5ebfd049ba773172441c268f2a17672 --- /dev/null +++ b/docs/java/extensions.md @@ -0,0 +1,84 @@ +--- +Order: 10 +Area: java +TOCTitle: Extensions +ContentId: 6076911c-276b-41a3-8510-0022c03c0ef6 +PageTitle: Java Extensions for Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: Popular Java Extensions for Visual Studio Code +--- +# Java Extensions for Visual Studio Code + +Visual Studio Code provides many features as a Java language editor. You can also install VS Code extensions to add more features for Java development. + +> **Tip:** To see how to install and manage your extensions, refer to the [extension documentation](/docs/editor/extension-gallery.md). + +## Recommended extensions + +To help set up Java on VS Code, there is the Microsoft [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack), which contains these popular extensions: + +1. [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) +2. [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) +3. [Java Test Runner](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-test) +4. [Maven for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-maven) +5. [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) +6. [Visual Studio IntelliCode](https://marketplace.visualstudio.com/items?itemName=VisualStudioExptTeam.vscodeintellicode) + +Install the Java Extension Pack + +There are also great extensions provided by Pivotal and Microsoft for Spring Boot development, including: + +1. [Spring Boot Tools](https://marketplace.visualstudio.com/items?itemName=Pivotal.vscode-spring-boot) +2. [Spring Initializr Java Support](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-initializr) +3. [Spring Boot Dashboard](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-boot-dashboard) + +## Popular extensions from the community + +Thanks to the great Java community around VS Code, there are many great community-created extensions as well. You can search for more Java extensions easily within the VS Code: + +1. Go to the **Extensions** view (`kb(workbench.view.extensions)`). +2. Filter the extensions list by typing 'java'. + +Here are a few useful extensions: + +1. [Tomcat](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) +2. [Jetty](https://marketplace.visualstudio.com/items?itemName=SummerSun.vscode-jetty) +3. [CheckStyle](https://marketplace.visualstudio.com/items?itemName=shengchen.vscode-checkstyle) +4. [Java Linter](https://marketplace.visualstudio.com/items?itemName=faustinoaq.javac-linter) +5. [Java Decompiler](https://marketplace.visualstudio.com/items?itemName=dgileadi.java-decompiler) +6. [Lombok Annotations Support](https://marketplace.visualstudio.com/items?itemName=GabrielBB.vscode-lombok) +7. [Java Properties](https://marketplace.visualstudio.com/items?itemName=ithildir.java-properties) +8. [Bazel](https://marketplace.visualstudio.com/items?itemName=BazelBuild.vscode-bazel) + +We also appreciate contributions to any of our existing extensions and we hope you'll create new Java extensions if you don't find what you're looking for in the Marketplace. We're especially looking for help in areas such as support for Gradle and other Java application servers. + +## Recommended extensions with great Java support + +We'd also like to recommend couple other extensions we believe are great to make VS Code even better for Java developers. + +1. [Live Share](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare) is a great tool to use when you need to collaborate with someone else on the same code base. +2. [LeetCode](https://marketplace.visualstudio.com/items?itemName=shengchen.vscode-leetcode) helps you sharpen your coding skills by solving LeetCode problems with Visual Studio Code. + +## Extension for container development + +You can use [Docker](https://marketplace.visualstudio.com/items?itemName=PeterJausovec.vscode-docker) extension to build docker images and work with image registries. + +[Kubernetes](https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.vscode-kubernetes-tools) extension provides an explorer view to manage clusters and the nodes inside. It also provides advanced syntax support for editing Kubernetes manifest files. + +## Recommended extensions for cloud (Azure) development + +### Team development + +* The [Azure Repos](https://marketplace.visualstudio.com/items?itemName=ms-vsts.team) extension makes it easy to connect to your Azure DevOps servers, allowing you to easily monitory builds, pull requests, and work items for your TFVC or Git source repositories. + +### Internet of Things + +* The [Azure IoT Toolkit](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-toolkit) for VS Code makes it easy to develop and connect your [IoT applications to Azure](https://docs.microsoft.com//azure/index#pivot=services&panel=iot). With this extension, you can interact with Azure IoT Hub, manage devices connected to Azure IoT Hub, and develop with code snippets for Azure IoT Hub. + +### General tools + +* The [Azure Tools for VS Code](https://marketplace.visualstudio.com/items?itemName=bradygaster.azuretoolsforvscode) adds commands to the **Command Palette** (`kb(workbench.action.showCommands)`) that make it easy to create and access Azure resources directly from VS Code. For example, you can create App Service Web Apps and Functions, Storage accounts, and browse to any number of resources in the Azure portal. + +* The [Azure Resource Manager Tools](https://marketplace.visualstudio.com/items?itemName=msazurermtools.azurerm-vscode-tools) provide a rich editing experience for Azure Resource Manager deployment templates and template language expressions. For example, IntelliSense for TLE function names, parameter references, signature help, Go to Definition, Peek Definition, and Peek References as well as Errors and Warnings, making it quick and easy to author Azure Resource Manager templates in VS Code. + +Visit [Azure Extensions](/docs/azure/extensions.md) to find more Azure extensions. \ No newline at end of file diff --git a/docs/java/images/java-azurefunctions/add-functions.gif b/docs/java/images/java-azurefunctions/add-functions.gif new file mode 100644 index 0000000000000000000000000000000000000000..7ff2c970c37935e9b3077e3d99a5d93ee899b79c --- /dev/null +++ b/docs/java/images/java-azurefunctions/add-functions.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3f5c8bac5ce32543d4cbacc4336a13a1615ee87a798a0fb5f6ad7d8b30ee1511 +size 590891 diff --git a/docs/java/images/java-azurefunctions/create-functions.png b/docs/java/images/java-azurefunctions/create-functions.png new file mode 100644 index 0000000000000000000000000000000000000000..26bffd76387c0d752ab3f027febf8c61c38c861f Binary files /dev/null and b/docs/java/images/java-azurefunctions/create-functions.png differ diff --git a/docs/java/images/java-azurefunctions/debug-functions.gif b/docs/java/images/java-azurefunctions/debug-functions.gif new file mode 100644 index 0000000000000000000000000000000000000000..6b5728ae3b0e6cce69ce79f1df9dfcaa2b80cc56 --- /dev/null +++ b/docs/java/images/java-azurefunctions/debug-functions.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:117012058abfe3a0c67b9d273aeb2f41fe111fa2aa8a204d4b988ce86b39f574 +size 1250471 diff --git a/docs/java/images/java-azurefunctions/deploy-functions.gif b/docs/java/images/java-azurefunctions/deploy-functions.gif new file mode 100644 index 0000000000000000000000000000000000000000..ababe1395ce6aca3d71505c57c57f7989f221f93 --- /dev/null +++ b/docs/java/images/java-azurefunctions/deploy-functions.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a558df45ca8d46cae6d886a7044f6e275f91c002ee8c2ae65cc105bc7fd44eed +size 789256 diff --git a/docs/java/images/java-azurefunctions/devicelogin.png b/docs/java/images/java-azurefunctions/devicelogin.png new file mode 100644 index 0000000000000000000000000000000000000000..5194a3c7a99b354b7671b8dc14095627129a17fb Binary files /dev/null and b/docs/java/images/java-azurefunctions/devicelogin.png differ diff --git a/docs/java/images/java-azurefunctions/devicelogin2.png b/docs/java/images/java-azurefunctions/devicelogin2.png new file mode 100644 index 0000000000000000000000000000000000000000..ba80b893326f1e4240ef4edd1786216a05868fd1 Binary files /dev/null and b/docs/java/images/java-azurefunctions/devicelogin2.png differ diff --git a/docs/java/images/java-debugging/attach-source.gif b/docs/java/images/java-debugging/attach-source.gif new file mode 100644 index 0000000000000000000000000000000000000000..bb594860fb6ba71599f1c12a90db0debca7e8ba4 --- /dev/null +++ b/docs/java/images/java-debugging/attach-source.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:63bbf4000702b8efbfa922f5b7736a7af1f06cb6205eac1aac60e7245c452cb0 +size 845938 diff --git a/docs/java/images/java-debugging/conditional-bp.gif b/docs/java/images/java-debugging/conditional-bp.gif new file mode 100644 index 0000000000000000000000000000000000000000..72389f7e5981088a6e42c8a2c786e24bed25926a --- /dev/null +++ b/docs/java/images/java-debugging/conditional-bp.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3308ad053dbe97b2cd2de63734d2806b06756e3dfc667833a6507c9271e68d59 +size 410912 diff --git a/docs/java/images/java-debugging/current-file.gif b/docs/java/images/java-debugging/current-file.gif new file mode 100644 index 0000000000000000000000000000000000000000..e20c3b2e5553a9078f1774ea5d9e67650bdac818 --- /dev/null +++ b/docs/java/images/java-debugging/current-file.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e3271736b6bec410d9af43042a23bfd9aa4c3ce8dc37c2ffc8efc2d30d106e95 +size 700529 diff --git a/docs/java/images/java-debugging/cwd-env.gif b/docs/java/images/java-debugging/cwd-env.gif new file mode 100644 index 0000000000000000000000000000000000000000..dbe33725a0b297587a64206d309cba90b345a297 --- /dev/null +++ b/docs/java/images/java-debugging/cwd-env.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4d1d24f78e860ffa9dac0a964d11a6bd5555d9f038a4fce440102a783012ff7a +size 907400 diff --git a/docs/java/images/java-debugging/expression-evaluation.gif b/docs/java/images/java-debugging/expression-evaluation.gif new file mode 100644 index 0000000000000000000000000000000000000000..b4e4e0868d826acc029f270c79b7220c3e4f5516 --- /dev/null +++ b/docs/java/images/java-debugging/expression-evaluation.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3c752c8f7188f766d801935da8c83f27015d2e633a2759ce3a450320418885ca +size 567765 diff --git a/docs/java/images/java-debugging/hcr.gif b/docs/java/images/java-debugging/hcr.gif new file mode 100644 index 0000000000000000000000000000000000000000..565e60e420c3a1d2dee201754d2e6c3be6287693 --- /dev/null +++ b/docs/java/images/java-debugging/hcr.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7c9cb77d4a990cf24108280fe09fa46559b159312a40b5b807478b4c2c02172d +size 792073 diff --git a/docs/java/images/java-debugging/java-codelens.gif b/docs/java/images/java-debugging/java-codelens.gif new file mode 100644 index 0000000000000000000000000000000000000000..b5a565bd42cf358bffca9dbc61de4b9cf3b64752 Binary files /dev/null and b/docs/java/images/java-debugging/java-codelens.gif differ diff --git a/docs/java/images/java-debugging/java-debug.gif b/docs/java/images/java-debugging/java-debug.gif new file mode 100644 index 0000000000000000000000000000000000000000..1a3cf5735a549718ee080f70ceb9dbc2c16078fb --- /dev/null +++ b/docs/java/images/java-debugging/java-debug.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:81b0a4ae8a3b98ff8f30c125000cc446221791827c6bd5532237d346e8196062 +size 1694905 diff --git a/docs/java/images/java-debugging/java9.gif b/docs/java/images/java-debugging/java9.gif new file mode 100644 index 0000000000000000000000000000000000000000..805ac28c37d68c87983e37dab5e2d9da04f53bd1 --- /dev/null +++ b/docs/java/images/java-debugging/java9.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8d19c4ca7786d5d4a3cdaf60b90a52e8842ba4fe2a1c9589b7cd2c29c5c96a4a +size 1709845 diff --git a/docs/java/images/java-debugging/junit.gif b/docs/java/images/java-debugging/junit.gif new file mode 100644 index 0000000000000000000000000000000000000000..1c9d6604150fb481eda2649e8b6c38209ffcd9b2 --- /dev/null +++ b/docs/java/images/java-debugging/junit.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5c7d9318b593f407d016c676acb2eb19d654aeee54e791c56c25b8de2a8463cf +size 1049909 diff --git a/docs/java/images/java-debugging/launch-in-terminal.gif b/docs/java/images/java-debugging/launch-in-terminal.gif new file mode 100644 index 0000000000000000000000000000000000000000..b91d50159c01561c0d1b6f626d60269aac72fd51 --- /dev/null +++ b/docs/java/images/java-debugging/launch-in-terminal.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:86af9e0c64188d92022647111714ea7687ac1e75aad1d4b1ed0e2bb5084d7243 +size 1550671 diff --git a/docs/java/images/java-debugging/logpoints.gif b/docs/java/images/java-debugging/logpoints.gif new file mode 100644 index 0000000000000000000000000000000000000000..d69dd705e7ef4abe2b493bedfb073c0c4373f186 --- /dev/null +++ b/docs/java/images/java-debugging/logpoints.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a74a168e954498cf4b0babcab6284f343e9b434ea01aee7cccd391e0fb1612ad +size 225855 diff --git a/docs/java/images/java-debugging/resolve-main.gif b/docs/java/images/java-debugging/resolve-main.gif new file mode 100644 index 0000000000000000000000000000000000000000..2613328e0bfa778fecdd88b9bc9079cb50f58e1e --- /dev/null +++ b/docs/java/images/java-debugging/resolve-main.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:05c025769a707d8443778a5c3cce4663cdac6a349fc8c19d0cda4d7694fe6ad0 +size 1009315 diff --git a/docs/java/images/java-debugging/single-file.gif b/docs/java/images/java-debugging/single-file.gif new file mode 100644 index 0000000000000000000000000000000000000000..4007ef5a3ea13b907fc0cc3895cc911f8e5027de --- /dev/null +++ b/docs/java/images/java-debugging/single-file.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:083e5537146fc42b7777fb2dc0360eb52866af03c6d408c4daee5e489fbce03c +size 546261 diff --git a/docs/java/images/java-debugging/step-filter.gif b/docs/java/images/java-debugging/step-filter.gif new file mode 100644 index 0000000000000000000000000000000000000000..e03d7a80e81b3897f4e647d354ae2be2aa66f40a --- /dev/null +++ b/docs/java/images/java-debugging/step-filter.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:281af2d70bc16f29c2cffc9aa4da7465f4db8c08fc58b6e9f5dfbcab810685b0 +size 1410269 diff --git a/docs/java/images/java-debugging/test-explorer.png b/docs/java/images/java-debugging/test-explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..40da3bcfb5ac33112a0d91bbed6ffd60082b833a --- /dev/null +++ b/docs/java/images/java-debugging/test-explorer.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:44c16a201c87a32cb7501d37e097f27c411528762e7f00aca72d2a2a3592ba36 +size 2680395 diff --git a/docs/java/images/java-editing/Intellisense(Intellicode).gif b/docs/java/images/java-editing/Intellisense(Intellicode).gif new file mode 100644 index 0000000000000000000000000000000000000000..02bf308a810d83794693f9eb82cc535f40a2de02 --- /dev/null +++ b/docs/java/images/java-editing/Intellisense(Intellicode).gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:af93fd88776c91708691ce6f9e485f1c58bee2b2edd484a4fdc4038e76da9c2d +size 858841 diff --git a/docs/java/images/java-editing/checkstyle.gif b/docs/java/images/java-editing/checkstyle.gif new file mode 100644 index 0000000000000000000000000000000000000000..3a6b5370787895e707c9e1810ff6e543bceda05c --- /dev/null +++ b/docs/java/images/java-editing/checkstyle.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:931974facb13247d619c9c426feba7db5d84a107f199ef20d9e12ded28a326a3 +size 4600829 diff --git a/docs/java/images/java-editing/code-editing.gif b/docs/java/images/java-editing/code-editing.gif new file mode 100644 index 0000000000000000000000000000000000000000..d29578675932774efc5a1290770ced563986b3c7 --- /dev/null +++ b/docs/java/images/java-editing/code-editing.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0b758082172239dd70a8f75ea283fa596d3914e064fc0d4c9cdf86ea558927aa +size 962329 diff --git a/docs/java/images/java-editing/getter-setter.gif b/docs/java/images/java-editing/getter-setter.gif new file mode 100644 index 0000000000000000000000000000000000000000..070f5c6959d94a2b291b0fb1123a7f8f51240819 --- /dev/null +++ b/docs/java/images/java-editing/getter-setter.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9dff3ce874f5b7b09f7a4d3335878ff8a80f776dd08ccad46509fd45e0ad9d7f +size 548014 diff --git a/docs/java/images/java-editing/intellicode.gif b/docs/java/images/java-editing/intellicode.gif new file mode 100644 index 0000000000000000000000000000000000000000..397902b465085c1d6501799bf4b491c7732bc075 --- /dev/null +++ b/docs/java/images/java-editing/intellicode.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:26934dac4e2909165b2cb4fee7edf231ebf9b7558cc71a4d5bdddb326223a7a5 +size 1674724 diff --git a/docs/java/images/java-editing/quick-fix.gif b/docs/java/images/java-editing/quick-fix.gif new file mode 100644 index 0000000000000000000000000000000000000000..96484b0d834fd9d83e26936fdf15674006468bf1 --- /dev/null +++ b/docs/java/images/java-editing/quick-fix.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5d424af0c7e82ce6cdc576c4b173df29c461c1315b6ca3f697e66ee4d79e59a2 +size 365526 diff --git a/docs/java/images/java-editing/refactor.gif b/docs/java/images/java-editing/refactor.gif new file mode 100644 index 0000000000000000000000000000000000000000..441be99baae22117071d2c9287cc4b8f64600f09 --- /dev/null +++ b/docs/java/images/java-editing/refactor.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:63873d5e23820219031ce4f64e4b023f1f105909f6dd692b2c7091ada9bc4a6c +size 662723 diff --git a/docs/java/images/java-editing/rename.gif b/docs/java/images/java-editing/rename.gif new file mode 100644 index 0000000000000000000000000000000000000000..b62287119685b4c2f58e5d5ad3a83b53676d3f91 --- /dev/null +++ b/docs/java/images/java-editing/rename.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:22d138709d574796022706976f2dbfdff38590eed6d964c0dad61090f466a730 +size 398396 diff --git a/docs/java/images/java-editing/search-in-file.gif b/docs/java/images/java-editing/search-in-file.gif new file mode 100644 index 0000000000000000000000000000000000000000..cb5a8d9171bbec0d5e6d2cda0b8146d9acf524d1 --- /dev/null +++ b/docs/java/images/java-editing/search-in-file.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:83e04bb396400d9013bac03268bf3a6cae95b96c10717fbb09af2a164825c561 +size 330781 diff --git a/docs/java/images/java-editing/search-in-workspace.gif b/docs/java/images/java-editing/search-in-workspace.gif new file mode 100644 index 0000000000000000000000000000000000000000..f6a7397b33ac77c12f8b97e6030078b6ad2c7387 --- /dev/null +++ b/docs/java/images/java-editing/search-in-workspace.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8e4b784dc44086d6a25a47a4cf3f5b5b52eb55c51590aa3cb04337d69ed1318f +size 458759 diff --git a/docs/java/images/java-editing/spring-navigation.png b/docs/java/images/java-editing/spring-navigation.png new file mode 100644 index 0000000000000000000000000000000000000000..44cc1ddfa265eda24aad38de47c54d2d7b29c1e9 --- /dev/null +++ b/docs/java/images/java-editing/spring-navigation.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:46873c4eeec29880eed7175619bfbc5b77944a00ac50b5128072095700e23c75 +size 209675 diff --git a/docs/java/images/java-project/create-project.gif b/docs/java/images/java-project/create-project.gif new file mode 100644 index 0000000000000000000000000000000000000000..3a1c1f5e857daaee5b821a51338b2b14a12aa489 --- /dev/null +++ b/docs/java/images/java-project/create-project.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5ec48ed66b7be754f12b5c1dc55557529ff72145fcf01791905b43b30b4bda53 +size 724187 diff --git a/docs/java/images/java-project/hierarchical.gif b/docs/java/images/java-project/hierarchical.gif new file mode 100644 index 0000000000000000000000000000000000000000..39abf496e7cf21a63574a527109e240b71b976bc --- /dev/null +++ b/docs/java/images/java-project/hierarchical.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cc788399b303ac221b6f22a444174338de37539ba60368b68d57b69ac26d39e6 +size 276682 diff --git a/docs/java/images/java-project/maven-archetype.gif b/docs/java/images/java-project/maven-archetype.gif new file mode 100644 index 0000000000000000000000000000000000000000..09d144bd6f494b8d00c1cb2a81ac59f77d2cfe03 --- /dev/null +++ b/docs/java/images/java-project/maven-archetype.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:341af7f37f05c2ab108741247e13436c7e35fe545f3b863e2cc4e96c74e06cc1 +size 937701 diff --git a/docs/java/images/java-project/maven-effective-pom.gif b/docs/java/images/java-project/maven-effective-pom.gif new file mode 100644 index 0000000000000000000000000000000000000000..3ddc82f1ec7f0b72f710e5f6a27d4d6e8b691ede --- /dev/null +++ b/docs/java/images/java-project/maven-effective-pom.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:025dac72b95d0eb8532667263fd1ae8aabf048b2c770086800ea36ff73cdc4bb +size 1005663 diff --git a/docs/java/images/java-project/maven-explorer.png b/docs/java/images/java-project/maven-explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..669c1736471929e1bb1c9affee790cb83aff6300 --- /dev/null +++ b/docs/java/images/java-project/maven-explorer.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:30f98e1704e03432bb49f870edc17c27482882a4f337cf9c41b8487e6d0ed390 +size 102504 diff --git a/docs/java/images/java-project/maven-history.gif b/docs/java/images/java-project/maven-history.gif new file mode 100644 index 0000000000000000000000000000000000000000..6503d80cb4e55de52a30fa563bf5f832daa81200 --- /dev/null +++ b/docs/java/images/java-project/maven-history.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fcb6cd39fc7f6375393e34509f955be5042c961e6551f1ad3d0e6e89e856d09c +size 933845 diff --git a/docs/java/images/java-project/maven-plugin-goal.gif b/docs/java/images/java-project/maven-plugin-goal.gif new file mode 100644 index 0000000000000000000000000000000000000000..3e2f8d33658d36afaffd5e2bfc8b9365557f4fab --- /dev/null +++ b/docs/java/images/java-project/maven-plugin-goal.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:067724ff6d26207e7a322bd726b943a185ea352381a2e3a6818e698d041f3059 +size 881898 diff --git a/docs/java/images/java-project/maven-pom-editing.gif b/docs/java/images/java-project/maven-pom-editing.gif new file mode 100644 index 0000000000000000000000000000000000000000..b4795945c2d6fece0286d95ad321079eda454747 --- /dev/null +++ b/docs/java/images/java-project/maven-pom-editing.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d612433814cf035cc25497a0d0d0a5e535614675a3c100cbd429d6cff776500e +size 908919 diff --git a/docs/java/images/java-project/maven-run.gif b/docs/java/images/java-project/maven-run.gif new file mode 100644 index 0000000000000000000000000000000000000000..d4f91031ee99650af46a4c759a58432292b5a0be --- /dev/null +++ b/docs/java/images/java-project/maven-run.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9b41d6253a1b303ffcea8824f1a8aacf30bf49f05522de8563388128732d6027 +size 705090 diff --git a/docs/java/images/java-project/multiple-source.gif b/docs/java/images/java-project/multiple-source.gif new file mode 100644 index 0000000000000000000000000000000000000000..4267e4be7bf5a39ef39c879cdf9ccb4085d3b2da --- /dev/null +++ b/docs/java/images/java-project/multiple-source.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dd7591b6895aa13f13bbbfc497cf01a9c9ec2a2188f7f7599016d8e31fb029fa +size 388547 diff --git a/docs/java/images/java-project/package-viewer.gif b/docs/java/images/java-project/package-viewer.gif new file mode 100644 index 0000000000000000000000000000000000000000..a04963d71597583046a8c9e9c26583f0599f873a --- /dev/null +++ b/docs/java/images/java-project/package-viewer.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b11e6b7552153637304b47ff067d48519dc14398c4b6c9f58810910ea9da26e7 +size 424691 diff --git a/docs/java/images/java-project/standalone.gif b/docs/java/images/java-project/standalone.gif new file mode 100644 index 0000000000000000000000000000000000000000..997b3943dc29f2ec80cb9f48c7365f8e35016513 --- /dev/null +++ b/docs/java/images/java-project/standalone.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3d3907423e1bc301024fe69b62adfe9b5e17145f725fab351c109a787d529044 +size 498870 diff --git a/docs/java/images/java-spring-boot/spring-code-edit.gif b/docs/java/images/java-spring-boot/spring-code-edit.gif new file mode 100644 index 0000000000000000000000000000000000000000..2432ccb48a0c494933f732557e5e1642720d1ac3 --- /dev/null +++ b/docs/java/images/java-spring-boot/spring-code-edit.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a18b5395cd33cd82aad5f9ec6c5b73c9999109b2af6c1c4a1cb1f4421f3fc64a +size 1549777 diff --git a/docs/java/images/java-spring-boot/spring-dashboard.gif b/docs/java/images/java-spring-boot/spring-dashboard.gif new file mode 100644 index 0000000000000000000000000000000000000000..4a22a9fc9560bdaab0dd37bff4e7d2e686e31a60 --- /dev/null +++ b/docs/java/images/java-spring-boot/spring-dashboard.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9f2e1e182f1afe97312a1d03f45aaeb16ac0ea19783e0395d2201258cb56b203 +size 1590622 diff --git a/docs/java/images/java-spring-boot/spring-initializr-edit.gif b/docs/java/images/java-spring-boot/spring-initializr-edit.gif new file mode 100644 index 0000000000000000000000000000000000000000..02b8024435be3c3681abe8fd7cdddc3d4897284b --- /dev/null +++ b/docs/java/images/java-spring-boot/spring-initializr-edit.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:69a3deec9e81cf34e00be174e74a7cc9c2f1bf5b3dc637da9fffd1e8feba3ab2 +size 674562 diff --git a/docs/java/images/java-spring-boot/spring-initializr.gif b/docs/java/images/java-spring-boot/spring-initializr.gif new file mode 100644 index 0000000000000000000000000000000000000000..3ed78e910eaaf101609937e5e1690c43c8508f7b --- /dev/null +++ b/docs/java/images/java-spring-boot/spring-initializr.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:02f42beca0580ff235f533007a1e6cc2b7a1cce364f0904e5d7f7e093f472bd8 +size 511241 diff --git a/docs/java/images/java-testing/displayname.png b/docs/java/images/java-testing/displayname.png new file mode 100644 index 0000000000000000000000000000000000000000..5c0d2d75d8415e0da68722f165fa206fb0ef8c3b Binary files /dev/null and b/docs/java/images/java-testing/displayname.png differ diff --git a/docs/java/images/java-testing/parameterizedtest.png b/docs/java/images/java-testing/parameterizedtest.png new file mode 100644 index 0000000000000000000000000000000000000000..d0479388c609f44c38e116bd657852b8afd6ca73 Binary files /dev/null and b/docs/java/images/java-testing/parameterizedtest.png differ diff --git a/docs/java/images/java-testing/report.gif b/docs/java/images/java-testing/report.gif new file mode 100644 index 0000000000000000000000000000000000000000..1740f80bebcbbdfeb76c280fd34cc274e3f7fbab --- /dev/null +++ b/docs/java/images/java-testing/report.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a9523caa48a69571ad14496ca15d0176893872fb68724674af601eff9a3c1c17 +size 340097 diff --git a/docs/java/images/java-testing/test-junit5.gif b/docs/java/images/java-testing/test-junit5.gif new file mode 100644 index 0000000000000000000000000000000000000000..d80a3eaca4dbbbe1de132d925c52eee5f2d4ea6b --- /dev/null +++ b/docs/java/images/java-testing/test-junit5.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3f3efb8e59a0c527689ebee727955f514d3bf7dc78f530df4b196521dc91676f +size 614292 diff --git a/docs/java/images/java-testing/testng.gif b/docs/java/images/java-testing/testng.gif new file mode 100644 index 0000000000000000000000000000000000000000..076901537b6414b9d987f03f0c748adef3d73eef --- /dev/null +++ b/docs/java/images/java-testing/testng.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ade114da2844fd624535e36e0b6f5f0f4cb8a7935e439162db1c5f368a345a97 +size 1116107 diff --git a/docs/java/images/java-tomcat-jetty/jetty.gif b/docs/java/images/java-tomcat-jetty/jetty.gif new file mode 100644 index 0000000000000000000000000000000000000000..f90379c24f977fd16811edb2f77ed79afd0f84bd --- /dev/null +++ b/docs/java/images/java-tomcat-jetty/jetty.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:55bc01bed6131809e0b392c61a5207dcc13aa1d83e85c700bdf90e5430716488 +size 3168320 diff --git a/docs/java/images/java-tomcat-jetty/tomcat-create-server.gif b/docs/java/images/java-tomcat-jetty/tomcat-create-server.gif new file mode 100644 index 0000000000000000000000000000000000000000..8a19a34cc3cf7f2c6d56818f899ad61c38bf9429 --- /dev/null +++ b/docs/java/images/java-tomcat-jetty/tomcat-create-server.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c2155796df1df702b90027c5ee3874f0ee4215e37c737a72ef14753dabf94cda +size 1666541 diff --git a/docs/java/images/java-tomcat-jetty/tomcat.gif b/docs/java/images/java-tomcat-jetty/tomcat.gif new file mode 100644 index 0000000000000000000000000000000000000000..3d3b1f4a429c12680af7eb3d74c6d6fc37e523ea --- /dev/null +++ b/docs/java/images/java-tomcat-jetty/tomcat.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:56eadc72716005c6b321742d62b271c08704c356005e35738feca0b79a2d07ab +size 2131679 diff --git a/docs/java/images/java-tutorial/create-file.gif b/docs/java/images/java-tutorial/create-file.gif new file mode 100644 index 0000000000000000000000000000000000000000..a9fb0ef0c158346665233f38f83084c5b8bde475 --- /dev/null +++ b/docs/java/images/java-tutorial/create-file.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3b166c82e4f02656e6d8928a9ed9fdff0968b6d6f2fa44590f5c4e5c20b7f77a +size 395432 diff --git a/docs/java/images/java-tutorial/edit-code.gif b/docs/java/images/java-tutorial/edit-code.gif new file mode 100644 index 0000000000000000000000000000000000000000..8fa68f18659fe276a061ef4aaae87480e1e9382e --- /dev/null +++ b/docs/java/images/java-tutorial/edit-code.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:066f28cd589ed338c64337944d3396e05a020150761d90ccaa3507fb0654b846 +size 431562 diff --git a/docs/java/images/java-tutorial/run-debug.gif b/docs/java/images/java-tutorial/run-debug.gif new file mode 100644 index 0000000000000000000000000000000000000000..142be759e6c7fe99c66d37750ce7ff396ba87e29 --- /dev/null +++ b/docs/java/images/java-tutorial/run-debug.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:57e2c2ec25b33925b31863767e8c18125d46cb1a462d1f68a7652ed8cf3fa130 +size 495362 diff --git a/docs/java/images/java-webapp/app-service-view.png b/docs/java/images/java-webapp/app-service-view.png new file mode 100644 index 0000000000000000000000000000000000000000..be5f98f381b4a04e7a0bbb43f2aa72c14e0b4fde Binary files /dev/null and b/docs/java/images/java-webapp/app-service-view.png differ diff --git a/docs/java/images/java-webapp/clone-repository.gif b/docs/java/images/java-webapp/clone-repository.gif new file mode 100644 index 0000000000000000000000000000000000000000..219efe5a14685cfc805383f1442a27ddcd246b3b --- /dev/null +++ b/docs/java/images/java-webapp/clone-repository.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:13f5bddc7bf916b3d5dc34ff3f364feb2b96d47a2ba24ec808c3c53fbd8ea072 +size 149977 diff --git a/docs/java/images/java-webapp/create-webapp.png b/docs/java/images/java-webapp/create-webapp.png new file mode 100644 index 0000000000000000000000000000000000000000..f19844b721dafd1db85491dd5f73622c70a89232 Binary files /dev/null and b/docs/java/images/java-webapp/create-webapp.png differ diff --git a/docs/java/images/java-webapp/debugging-status-bar.png b/docs/java/images/java-webapp/debugging-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..59e4abe9e620d74753e8de67a2d714a3193c641b --- /dev/null +++ b/docs/java/images/java-webapp/debugging-status-bar.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:09c6cc54b6c0a0bd825e95fc1891f861613f2c37cd5dab0e32f7a6041e1ee1b1 +size 108537 diff --git a/docs/java/images/java-webapp/debugging.png b/docs/java/images/java-webapp/debugging.png new file mode 100644 index 0000000000000000000000000000000000000000..1d7f04767d98bf18be8ee51b006be061b96dace9 --- /dev/null +++ b/docs/java/images/java-webapp/debugging.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:85efb591b09dddb9287b533c84611fae6c54ef408237ff115202fd372d51ad26 +size 145752 diff --git a/docs/java/images/java-webapp/deploy-success.png b/docs/java/images/java-webapp/deploy-success.png new file mode 100644 index 0000000000000000000000000000000000000000..ac6bb622501e6749e5cd4a0d6e8d475e64e823f5 Binary files /dev/null and b/docs/java/images/java-webapp/deploy-success.png differ diff --git a/docs/java/images/java-webapp/deploy-webapp.png b/docs/java/images/java-webapp/deploy-webapp.png new file mode 100644 index 0000000000000000000000000000000000000000..941c261667a2e6fa5eb38ea02951bff41d1823b6 --- /dev/null +++ b/docs/java/images/java-webapp/deploy-webapp.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:37a4c32081db48b7e366fefb1b45651a7cf8cb2408b3e122abe415b8358952ab +size 210587 diff --git a/docs/java/images/java-webapp/devicelogin.png b/docs/java/images/java-webapp/devicelogin.png new file mode 100644 index 0000000000000000000000000000000000000000..5194a3c7a99b354b7671b8dc14095627129a17fb Binary files /dev/null and b/docs/java/images/java-webapp/devicelogin.png differ diff --git a/docs/java/images/java-webapp/devicelogin2.png b/docs/java/images/java-webapp/devicelogin2.png new file mode 100644 index 0000000000000000000000000000000000000000..ba80b893326f1e4240ef4edd1786216a05868fd1 Binary files /dev/null and b/docs/java/images/java-webapp/devicelogin2.png differ diff --git a/docs/java/images/java-webapp/greeting-cloud.png b/docs/java/images/java-webapp/greeting-cloud.png new file mode 100644 index 0000000000000000000000000000000000000000..bcc065fe066ca119331a41a1ff5c517f154b5795 Binary files /dev/null and b/docs/java/images/java-webapp/greeting-cloud.png differ diff --git a/docs/java/images/java-webapp/greeting-from-spring.png b/docs/java/images/java-webapp/greeting-from-spring.png new file mode 100644 index 0000000000000000000000000000000000000000..e75e9e6e4bd2787860603cfae4c03480a2fd6aee Binary files /dev/null and b/docs/java/images/java-webapp/greeting-from-spring.png differ diff --git a/docs/java/images/java-webapp/greeting.png b/docs/java/images/java-webapp/greeting.png new file mode 100644 index 0000000000000000000000000000000000000000..8fcd88e728b4c37fc1221e8035afe60af89d311b Binary files /dev/null and b/docs/java/images/java-webapp/greeting.png differ diff --git a/docs/java/images/java-webapp/install-extensions.gif b/docs/java/images/java-webapp/install-extensions.gif new file mode 100644 index 0000000000000000000000000000000000000000..081c0614b41daac75740b71791b70e31adf3d7c9 --- /dev/null +++ b/docs/java/images/java-webapp/install-extensions.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:154233e61e36c3c8c5a7a0c64e6083221daf2e2cf3442f3c20d79b6e6eae9285 +size 395023 diff --git a/docs/java/images/java-webapp/overview.png b/docs/java/images/java-webapp/overview.png new file mode 100644 index 0000000000000000000000000000000000000000..1865d371474a1315ceb88e24ab4e4a7f48dda734 Binary files /dev/null and b/docs/java/images/java-webapp/overview.png differ diff --git a/docs/java/images/java-webapp/remove-auth.png b/docs/java/images/java-webapp/remove-auth.png new file mode 100644 index 0000000000000000000000000000000000000000..846587a0ae44cb2951239c3f7559fa6f36e305b8 Binary files /dev/null and b/docs/java/images/java-webapp/remove-auth.png differ diff --git a/docs/java/images/java-webapp/restart-application.png b/docs/java/images/java-webapp/restart-application.png new file mode 100644 index 0000000000000000000000000000000000000000..e4ef99198ca788a6cb399cb36e053ee53da5baa1 Binary files /dev/null and b/docs/java/images/java-webapp/restart-application.png differ diff --git a/docs/java/images/java-webapp/run-spring-boot.gif b/docs/java/images/java-webapp/run-spring-boot.gif new file mode 100644 index 0000000000000000000000000000000000000000..303cab4818170233c9eee7c9ddba7eedff288f40 --- /dev/null +++ b/docs/java/images/java-webapp/run-spring-boot.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3b5d573fa4a969ec23a081863cffaff4499599f561169cd7cc9881e0005b696d +size 845566 diff --git a/docs/java/java-azurefunctions.md b/docs/java/java-azurefunctions.md new file mode 100644 index 0000000000000000000000000000000000000000..c55d1acb4285634e010c7e7cf5924374f3cb5bc6 --- /dev/null +++ b/docs/java/java-azurefunctions.md @@ -0,0 +1,239 @@ +--- +Order: 9 +Area: java +TOCTitle: Azure Functions in Java +ContentId: a3071f40-4987-4054-99cb-3d122d23bf47 +PageTitle: Building Azure Functions in Java with Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: Using Visual Studio Code for developing, debugging and deploying your Java Azure Functions application. +--- +# Azure Functions in Java with VS Code + +Azure Functions let you execute your source code in a [serverless](https://azure.microsoft.com/overview/serverless-computing/) environment without having to first create a VM or publish a web application. + +This tutorial walks you through creating and deploying a Java Azure Functions application using the [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) extension in Visual Studio Code. You'll be able to test the function locally and then deploy it to Azure. When you're done, you'll have a HTTP-triggered function app running in Azure. + +## Prerequisites + +To develop Azure Functions with Java, you'll need the following tools installed: + +- [Java Developer Kit](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) (JDK), version 1.8. +- [Apache Maven](https://maven.apache.org), version 3.0 or above. + +>**Important**: The `JAVA_HOME` environment variable must be set to the install location of the JDK to complete this tutorial. + +## Install the Azure Functions extension + +The [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) extension is used to create, manage, and deploy Functions Apps on Azure. It supports both Java and JavaScript Functions with features including: + +- Create new project. +- Create new Function from template. +- Debug Function projects locally. +- View Azure Function Apps. +- Create, delete, start, stop, and restart Azure Function Apps. +- JSON IntelliSense for `function.json`, `host.json` and `proxies.json` files. + +In this tutorial, we will leverage this extension to create a Java Azure Functions App. For a more command line Maven-centric experience, you can also check out the [Maven Functions Tutorial](https://docs.microsoft.com/en-gb/azure/azure-functions/functions-create-first-java-maven). The Java support of this extension leverages a lot from the [Maven Plugin for Azure Functions](https://github.com/Microsoft/azure-maven-plugins/tree/master/azure-functions-maven-plugin). + +To install the Azure Functions extension, open the Extensions view (`kb(workbench.view.extensions)`) and search for `azure functions` to filter the results. Select the Microsoft [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) extension. + +## Generate a new Functions project + +Once you've installed the Azure Functions extension, you can easily create a new project by: + +1. Click **Create New Project** button on the **FUNCTIONS** Explorer within the **Azure** tab. +2. Select target folder. +3. Select Java the target language. +4. Fill in the parameters. + +The extension uses [Maven archetypes](https://maven.apache.org/guides/introduction/introduction-to-archetypes.html) to create the function project in the folder you specified. + +![Create Functions Project](images/java-azurefunctions/create-functions.png) + +Within the created project, there's a simple HTTP triggered 'Hello World' Function which reads the input from HTTP query string or body and returns it back immediately. + +```java +/** + * Azure Functions with HTTP Trigger. + */ +public class Function { + @FunctionName("HttpTrigger-Java") + public HttpResponseMessage httpHandler( + @HttpTrigger(name = "req", methods = {"get", "post"}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage> request, + final ExecutionContext context) { + context.getLogger().info("Java HTTP trigger processed a request."); + + // Parse query parameter + String query = request.getQueryParameters().get("name"); + String name = request.getBody().orElse(query); + + if (name == null) { + return request.createResponse(400, "Please pass a name on the query string or in the request body"); + } else { + return request.createResponse(200, "Hello, " + name); + } + } +} +``` + +## Install the Azure Functions Core Tools + +**Note**: This step is optional and only required to locally run and debug your Java Functions source code. + +The [Azure Functions Core Tools 2.0](https://www.npmjs.com/package/azure-functions-core-tools) provides a local development environment for writing, running, and debugging Azure Functions. The installation package for v2 is a self-contained cross-platform package. + +### Windows + +```bash +npm i -g azure-functions-core-tools@core --unsafe-perm true +``` + +### macOS + +**Homebrew**: + +```bash +brew tap azure/functions +brew install azure-functions-core-tools +``` + +### Linux + +**Ubuntu/Debian** + +1. Register the Microsoft Product key as trusted. + +```bash +curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg +sudo mv microsoft.gpg /etc/apt/trusted.gpg.d/microsoft.gpg +``` + +2. Add source + +**Ubuntu 16.04 / Linux Mint 18** + +```bash +sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-ubuntu-xenial-prod xenial main" > /etc/apt/sources.list.d/dotnetdev.list' +sudo apt-get update +``` + +3. Install + +```bash +sudo apt install azure-functions-core-tools +``` + +You can learn more by reading the [Code and test Azure Functions locally](https://docs.microsoft.com/azure/azure-functions/functions-run-local) How-to guide. + +**NOTE**: [npm](https://www.npmjs.com/) can be used on all platforms. On Unix platforms, you may need to specify `--unsafe-perm` if you are running `npm` with sudo. This is necessary due to npm's post install script behavior. + +**NOTE**: If you're running the v2 on Windows, Linux, or macOS, make sure to [enable the `preview` runtime](https://docs.microsoft.com/azure/azure-functions/functions-versions) in function app settings, otherwise you may not see the same results as running locally. + +## Run and debug the function locally + +Once the function is created, press `kb(workbench.action.debug.start)` to start the function. Behind the scene, we've configured the `launch.json` debugger configuration file (created under the project `.vscode` folder) to build the functions project and then start the local runtime provided by [Azure Functions Core Tools 2.0](https://www.npmjs.com/package/azure-functions-core-tools). If you would like to debug your function, set a break point (`kb(editor.debug.action.toggleBreakpoint)`) and then send a request to trigger the HTTP function. + +```bash +curl -w '\n' -d LocalFunction http://localhost:7071/api/httptrigger-java +``` + +You should see: + +```bash +Hello LocalFunction! +``` + +![Debug Functions Project](images/java-azurefunctions/debug-functions.gif) + +Use `kbstyle(Ctrl+C)` in the terminal to stop the function code. + +## Deploy the function to Azure + +If you don't have an Azure subscription, you can sign up for a [free Azure account](https://azure.microsoft.com/pricing/free-trial/ +). + +Create your free Azure account + +The deploy process leverages the [Azure Account](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account) extension (installed along with the Azure Functions extension as an dependency) and you need to sign in with your Azure subscription. If you do not have an Azure subscription, [sign up today](https://azure.microsoft.com//free/?b=16.48) for a free 30 day account and get $200 in Azure Credits to try out any combination of Azure services. + +To log into Azure, run **Azure: Sign In** from the **Command Palette** (`kb(workbench.action.showCommands)`). You can then sign into your account using the **Device Login** flow. Click on **Copy & Open** to open your default browser. + +![Azure sign in code](images/java-azurefunctions/devicelogin.png) + +Paste in the access code and continue the sign in process. + +![Azure Device Login](images/java-azurefunctions/devicelogin2.png) + +After signing in, click **Deploy to Function App** button, select the folder of the project you would like to deploy from, and follow the prompts to configure your function project. + +![Deploy Functions](images/java-azurefunctions/deploy-functions.gif) + +Once the function is deployed, test the function app running on Azure using curl: + +```bash +curl -w '\n' https://fabrikam-function-20170920120101928.azurewebsites.net/api/hello -d AzureFunctions +``` + +You should see: + +```bash +Hello AzureFunctions! +``` + +## Add additional functions to the project + +The extension also supports adding new functions to the existing project: + +1. Click **Add Function** button on the **AZURE FUNCTIONS** Explorer bar. +2. Select project folder. +3. Select function type. +4. Fill in the parameters for this function type. + +![Add Functions](images/java-azurefunctions/add-functions.gif) + +## Remote debugging + +Although the local core tool from Azure Functions is running the same code as in the cloud, sometimes environment differences may cause your function to behave differently. Using remote debugging, you can troubleshoot those issues. + +There is a special [Remote Debugging Tool](https://www.npmjs.com/package/cloud-debug-tools) to help you set up the remote debugging session which you can install it via [npm](https://www.npmjs.com/): + +```bash +npm install -g cloud-debug-tools +``` + +Once it's installed, run the tool to attach to the running Function on Azure + +```bash +dbgproxy fabrikam-function-20170920120101928.azurewebsites.net +``` + +The tool depends on the [Azure CLI](https://docs.microsoft.com/cli/azure) to fetch your credentials so make sure you've logged in with the same account. + +```bash +az login +``` + +The tool will then figure out the rest for you. Once it's connected to the running Function, add a new debugging configuration to attach to the local port opened by it. + +```bash +{ + "name": "Attach to Azure Functions on Cloud", + "type": "java", + "request": "attach", + "hostName": "localhost", + "port": 8898 +} +``` + +Now you can set a break point and attach to your cloud function using VS Code. When you launch a debug session with the above configuration, you can step through it just like you did locally. It's also useful if you don't have .Net Core and the Azure Functions CLI core tool installed on your local environment and you want to jump start within the cloud directly. + +Recently, we've also enabled remote debugging Azure Functions through the Functions Extension. To use this feature, you need to set `azureFunctions.enableRemoteDebugging` to true. And the entrance is called `Attach debugger`. Details could be found [Remote Debugging Java Functions in VS Code](https://github.com/Microsoft/vscode-azurefunctions/blob/master/docs/remotedebug.md). + +## Next steps + +You have created a Java function app with a simple HTTP trigger and deployed it to Azure Functions. + +- More information on developing Java Functions + - [Java Functions developer guide](https://docs.microsoft.com/azure/azure-functions/functions-reference-java) + - [Quickstart with Maven](https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-java-maven) +- To learn more about Java Debugging features, see [Java Debugging Tutorial](/docs/java/java-debugging.md). diff --git a/docs/java/java-debugging.md b/docs/java/java-debugging.md new file mode 100644 index 0000000000000000000000000000000000000000..18de2cc1c978158ccf785f81b241f4488f92d321 --- /dev/null +++ b/docs/java/java-debugging.md @@ -0,0 +1,193 @@ +--- +Order: 3 +Area: java +TOCTitle: Debugging +ContentId: 929e5410-3bfe-4107-b331-565afe5d341f +PageTitle: Java Debug in Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: See how you can debug your Java code locally, and in the cloud. +MetaSocialImage: +--- + +# Debugging Java in Visual Studio Code + +Visual Studio Code allows you to debug Java applications through the [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) extension. It's a lightweight Java debugger based on [Java Debug Server](https://github.com/Microsoft/java-debug), which extends the [Language Support for Java by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java). + +Here's a list of supported debugging features: + +- Launch/Attach +- Breakpoints +- Exceptions +- Pause & Continue +- Step In/Out/Over +- Variables +- Call Stacks +- Threads +- Debug Console +- Evaluation +- Hot Code Replace + +The Java debugger is an open source project, which welcomes contributors to collaborate through GitHub repositories: + +- [Debugger for Java Extension](https://github.com/Microsoft/vscode-java-debug) +- [Java Debugger Server for Visual Studio Code](https://github.com/Microsoft/java-debug) + +## Install + +For the debugger to work, you also need to have the [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) extension installed. To make it easier, there is a [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack) which bundles the [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java), the [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) and several other popular Java [extensions](/docs/java/extensions.md). + +You can manually install the extension pack from the Extensions view (`kb(workbench.view.extensions)`) by typing `vscode-java-pack` in the search box. You will also be prompted to install the Java Extension Pack when you edit a Java file in VS Code for the first time. + +## Use + +It's easy to run and debug your Java application as we provide several entry points for that. + +### CodeLens + +Once the debugger is activated, you will find **Run|Debug** on the CodeLens of your `main()` function. + +![CodeLens](images/java-debugging/java-codelens.gif) + +### Clicking F5 + +Once you click `kb(workbench.action.debug.start)`, the debugger will automatically find the entry point of your project and start debugging. + +![Resolving Main Class](images/java-debugging/resolve-main.gif) + +It's possible that there might be multiple debugging configurations for your project and you can always add and modify those then select the desired one to run. + +![Java Debugging](images/java-debugging/java-debug.gif) + +If there's no debug configuration file `launch.json` in your project, the debugger will automatically find the main class and generate the configuration for you to launch your application. VS Code keeps debugging configuration information in a `launch.json` file located in a `.vscode` folder in your workspace (project root folder) or in your [user settings](/docs/editor/debugging.md#global-launch-configuration) or [workspace settings](/docs/editor/multi-root-workspaces.md#workspace-launch-configurations). For more details, please read [Launch configurations](/docs/editor/debugging.md#launch-configurations) + +There's also a convenient setting for debugging `current file` so the editor knows which file is currently active and choose it as the entry point. + +![Java Debugging](images/java-debugging/current-file.gif) + +### Debugging single files + +VS Code can run and debug single Java files without any project. + +![Debug Single File](images/java-debugging/single-file.gif) + +### Debugging external files + +The Java debugger also supports external source files. This lets you debug third party classes when they are inside a JAR or a source attachment. Set your breakpoints in those classes before you start debugging. You can also attach missing source code with a `zip/jar` file using the Context menu **Attach Source** action. + +![Debug Single File](images/java-debugging/attach-source.gif) + +Java 9 is supported with VS Code Java Debugger as well. + +![Java 9 Support](images/java-debugging/java9.gif) + +### Debug session inputs + +The default Debug Console in VS Code doesn't support inputs. If your program need inputs from a terminal, you can use the Integrated Terminal (`kb(workbench.action.terminal.toggleTerminal)`) within VS Code or an external terminal to launch it. + +![Launch in Terminal](images/java-debugging/launch-in-terminal.gif) + +### Step filtering + +Step filter is supported by the extension to filter out types that you do not wish to see or step through while debugging. With this feature, you can configure the packages to filter within your `launch.json` so they could be skipped when you step through. + +![Step Filter](images/java-debugging/step-filter.gif) + +### Expression evaluation + +The debugger also lets you evaluate expressions in the **WATCH** window as well as the Debug Console. You can also use this feature for conditional breakpoint setting. + +![Expression Evaluation](images/java-debugging/expression-evaluation.gif) + +### Conditional breakpoint + +With the help of expression evaluation, the debugger also supports conditional breakpoint. You can set your breakpoint to break when expression evaluates to true. + +![Conditional Breakpoint](images/java-debugging/conditional-bp.gif) + +### Hot Code replacement + +Another advanced feature the debugger supports is 'Hot Code' replacement. Hot code replacement (HCR) is a debugging technique whereby the Java debugger transmits new class files over the debugging channel to another Java Virtual Machine (JVM). HCR facilitates experimental development and fosters iterative trial-and-error coding. With this new feature, you can start a debugging session and change a Java file in your development environment, and the debugger will replace the code in the running JVM. No restart is required, which is why it’s called "hot". Below is an illustration of how you can use HCR with Debugger for Java in VS Code. + +![Hot Code Replacement](images/java-debugging/hcr.gif) + +### Logpoints + +[Logpoints](/blogs/2018/07/12/introducing-logpoints-and-auto-attach.md#introducing-logpoints) is also supported by Java Debugger. Logpoints allow you to send output to debug console without editing code. They’re different from breakpoints because they don’t stop the execution flow of your application. + +![Hot Code Replacement](images/java-debugging/logpoints.gif) + +## Configuration + +There are many options and settings available to configure the debugger. For example, configuring the current working directory (cwd) and environment variables is easily done with launch options. + +![Configure Variables](images/java-debugging/cwd-env.gif) + +Consult the documentation for the [Language Support for Java by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) extension for help with setting up your project. + +Below are all the configurations available for `Launch` and `Attach`, for more information about how to write the `launch.json` file, refer to [Debugging](/docs/editor/debugging.md). + +### Launch + +- `mainClass` (required) - The fully qualified class name (e.g. [java module name/]com.xyz.MainApp) or the java file path of the program entry. +- `args` - The command-line arguments passed to the program. Use `"${command:SpecifyProgramArgs}"` to prompt for program arguments. It accepts a string or an array of string. +- `sourcePaths` - The extra source directories of the program. The debugger looks for source code from project settings by default. This option allows the debugger to look for source code in extra directories. +- `modulePaths` - The modulepaths for launching the JVM. If not specified, the debugger will automatically resolve from current project. +- `classPaths` - The classpaths for launching the JVM. If not specified, the debugger will automatically resolve from current project. +- `encoding` - The `file.encoding` setting for the JVM. If not specified, 'UTF-8' will be used. Possible values can be found in http://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html. +- `vmArgs` - The extra options and system properties for the JVM (for example -Xms\ -Xmx\ -D\=\), it accepts a string or an array of string. +- `projectName` - The preferred project in which the debugger searches for classes. There could be duplicated class names in different projects. This setting also works when the debugger looks for the specified main class when launching a program. It is required when the workspace has multiple Java projects, otherwise the expression evaluation and conditional breakpoint may not work. +- `cwd` - The working directory of the program. Defaults to `${workspaceFolder}`. +- `env` - The extra environment variables for the program. +- `stopOnEntry` - Automatically pause the program after launching. +- `console` - The specified console to launch the program. Defaults to `internalConsole`. + - `internalConsole` - VS Code debug console (input stream not supported). + - `integratedTerminal` - VS Code integrated terminal. + - `externalTerminal` - External terminal that can be configured in user settings. +- `stepFilters` - Skip specified classes or methods when stepping. + - `classNameFilters` - Skip the specified classes when stepping. Class names should be fully qualified. Wildcard is supported. + - `skipSynthetics` - Skip synthetic methods when stepping. + - `skipStaticInitializers` - Skip static initializer methods when stepping. + - `skipConstructors` - Skip constructor methods when stepping. + +### Attach + +- `hostName` (required) - The host name or IP address of remote debuggee. +- `port` (required) - The debug port of remote debuggee. +- `timeout` - Time out value before reconnecting, in milliseconds (default to 30000 ms). +- `sourcePaths` - The extra source directories of the program. The debugger looks for source code from project settings by default. This option allows the debugger to look for source code in extra directories. +- `projectName` - The preferred project in which the debugger searches for classes. There could be duplicated class names in different projects. It is required when the workspace has multiple java projects, otherwise the expression evaluation and conditional breakpoint may not work. +- `stepFilters` - Skip specified classes or methods when stepping. + - `classNameFilters` - Skip the specified classes when stepping. Class names should be fully qualified. Wildcard is supported. + - `skipSynthetics` - Skip synthetic methods when stepping. + - `skipStaticInitializers` - Skip static initializer methods when stepping. + - `skipConstructors` - Skip constructor methods when stepping. + +### User Settings + +- `java.debug.logLevel`: minimum level of debugger logs that are sent to VS Code, defaults to `warn`. +- `java.debug.settings.showHex`: show numbers in hex format in "Variables" viewlet, defaults to `false`. +- `java.debug.settings.showStaticVariables`: show static variables in "Variables" viewlet, defaults to `true`. +- `java.debug.settings.showQualifiedNames`: show fully qualified class names in "Variables" viewlet, defaults to `false`. +- `java.debug.settings.maxStringLength`: the maximum length of string displayed in "Variables" or "Debug Console" viewlet, the string longer than this length will be trimmed, defaults to `0` which means no trim is performed. +- `java.debug.settings.enableHotCodeReplace`: enable hot code replace for Java code. Make sure the auto build is not disabled for [VSCode Java](https://github.com/redhat-developer/vscode-java). See the [wiki page](https://github.com/Microsoft/vscode-java-debug/wiki/Hot-Code-Replace) for more information about usages and limitations. +- `java.debug.settings.enableRunDebugCodeLens`: enable the CodeLens provider for the run and debug buttons over main entry points, defaults to `true`. +- `java.debug.settings.forceBuildBeforeLaunch`: force building the workspace before launching java program, defaults to `true`. + +## Troubleshooting + +Detailed troubleshooting guide could be found in our [GitHub Repository](https://github.com/Microsoft/vscode-java-debug/blob/master/Troubleshooting.md). + +## Feedback and questions + +You can find the full list of issues at [Issue Tracker](https://github.com/Microsoft/vscode-java-debug/issues). You can submit a [bug or feature suggestion](https://github.com/Microsoft/vscode-java-debug/issues/new) and participate in the community driven [Gitter](https://gitter.im/Microsoft/vscode-java-debug) channel. + +## Next steps + +Read on to find out about: + +* [Debugging](/docs/editor/debugging.md) - Find out how to use the debugger in VS Code with your project for any language. + +And for Java: + +* [Java Testing](/docs/java/java-testing.md) +* [Java Extensions](/docs/java/extensions.md) - Learn about more useful Java extensions for VS Code. diff --git a/docs/java/java-editing.md b/docs/java/java-editing.md new file mode 100644 index 0000000000000000000000000000000000000000..1ca77b49c9dc10fdafef22041fd8a9bc95b03814 --- /dev/null +++ b/docs/java/java-editing.md @@ -0,0 +1,103 @@ +--- +Order: 2 +Area: java +TOCTitle: Editing Code +ContentId: 843e139a-9e3c-4b4f-95d1-32a9a7480e8e +PageTitle: Editing Java in Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: Editing Java in Visual Studio Code with IntelliSense, Refactoring and Formatting. +--- +# Editing Java in Visual Studio Code + +Visual Studio Code is a source code editor first and foremost with rich editing [features](/docs/editor/codebasics.md). In this document, we will go through a few Java-specific features, which are helpful when working with Java. + +## Code editing and navigation + +With the [Outline view](/docs/getstarted/userinterface.md#outline-view), you can conveniently navigate your methods within the same class. Editing code is also easy with IntelliSense for smart code completions and signature details. You can use code snippets as well as various code actions such as generating Getters/Setters and organizing imports to further boost your productivity. + +![Code Editing](images/java-editing/code-editing.gif) + +Java support in Visual Studio Code detects issues within your code automatically, and provides you with Quick Fix suggestions. + +![Quick Fix](images/java-editing/quick-fix.gif) + +As a Java editor, it also supports CodeLens (references) and Javadoc hovers and highlights out of box. + +### Search for symbols + +You can search for symbols in the current file or workspace to navigate your code more quickly. + +To search for a symbol in the current file, use __Quick Open__ (`kb(workbench.action.quickOpen)`) then enter the '@' command, then enter the name of the symbol you're looking for. A list of potential matches will appear and be filtered as you type. Choose from the list of matches to navigate to its location. + +![Search in local file](images/java-editing/search-in-file.gif) + +To search for a symbol in the current workspace, start by pressing `kb(workbench.action.showAllSymbols)`, then enter the name of the symbol. A list of potential matches will appear as before. If you choose a match that was found in a file that's not already open, the file will be opened before navigating to the match's location. Alternatively, you can also use __Quick Open__ (`kb(workbench.action.quickOpen)`) then enter the '#' command to search the current workspace. `kb(workbench.action.showAllSymbols)` is just the shortcut for the '#' commands, so everything works the same. + +![Search in workspace](images/java-editing/search-in-workspace.gif) + +### Peek Definition + +You can take a quick look at how a symbol was defined by using the Peek Definition feature. This feature displays a few lines of code near the definition inside a peek window, so you can take a look without navigating away from your current location. + +To peek at a symbol's definition, place your cursor on the symbol anywhere it's used in your source code and then press `kb(editor.action.peekDefinition)`. Alternatively, you can choose __Peek Definition__ from the context menu (right-click, then choose __Peek Definition__). + +### Go to Definition + +You can also quickly navigate to where a symbol is defined by using the Go to Definition feature. + +To go to a symbol's definition, place your cursor on the symbol anywhere it is used in your source code and then press `kb(editor.action.revealDefinition)`. Alternatively, you can choose __Go to Definition__ from the context menu (right-click, then choose __Go to Definition__). When there's only one definition of the symbol, you'll navigate directly to its location, otherwise the competing definitions are displayed in a peek window as described in the previous section and you have to choose the definition that you want to go to. + +### Navigating code with Spring Boot + +[Spring Boot Tools](https://marketplace.visualstudio.com/items?itemName=Pivotal.vscode-spring-boot) extension provides enhanced navigation and code completion support for Spring Boot projects. + +* `@/` shows all defined request mappings (mapped path, request method, source location) +* `@+` shows all defined beans (bean name, bean type, source location) +* `@>` shows all functions (prototype implementation) +* `@` shows all Spring annotations in the code + +![Search in workspace](images/java-editing/spring-navigation.png) + +To learn more about Spring Boot support with Visual Studio Code, read [Spring Boot in Visual Studio Code](/docs/java/java-spring-boot.md). + +### IntelliSense + +Code completion in Visual Studio Code for Java is provided by [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java). The extension is powered by the same [Java development tools (JDT)](https://www.eclipse.org/jdt/) behind Eclipse, so you can expect the same level of support. + +In addition, there's also AI-assisted IntelliSense called [IntelliCode](https://visualstudio.microsoft.com/services/intellicode/). It saves you time by putting what you're most likely to use at the top of your completion list. IntelliCode recommendations are based on thousands of open-source projects on GitHub each with over 100 stars, so it’s trained on the most common usages from high quality projects. When combined with the context of your code, the completion list is tailored to promote those practices. Here's IntelliCode for Java in action. + +![IntelliCode](images/java-editing/intellicode.gif) + +IntelliCode works well with popular Java libraries and frameworks like Java SE and Spring. It will help you whether you are doing monolithic web apps or modern microservices. + +## Refactoring + +Here we will show you the most used refactoring features for Java in Visual Studio Code, namely rename, extract methods and variables. + +### Rename + +Rename allows you to rename variables, classes, methods, packages, folders, and almost any Java identifiers. When you rename an identifier, all references to that identifier are also renamed. The shortcut to invoke the Rename refactoring is `kb(editor.action.rename)`. When you invoke the shortcut on an identifier in the editor, a small box displays within the editor itself where you can change the identifier name. When you press `kbstyle(Enter)`, all references to that identifier are changed too. + +![Rename](images/java-editing/rename.gif) + +### Extract methods and variables + +Extract to constant, method, and local variables all come in handy with Java on Visual Studio Code. + +![Refactor](images/java-editing/refactor.gif) + +### Generate getters and setters + +You can bulk generate getters and setters for all new member variables. + +![GettersSetters](images/java-editing/getter-setter.gif) + +## Formatting + +[Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) also provides [formatting settings](https://github.com/redhat-developer/vscode-java/wiki/Formatter-settings). You can export an Eclipse formatter file and then use it for your project in VS Code. + +In addition, there's a [Checkstyle for Java](https://marketplace.visualstudio.com/items?itemName=shengchen.vscode-checkstyle) extension, which you can use with either existing `checkstyle` configurations (Google's or Sun's Check) or your own customized files. When opening or saving a Java file, the extension will check the file format and provide quick fixes if possible. + +![Checkstyle](images/java-editing/checkstyle.gif) + +For more details about [Checkstyle for Java](https://marketplace.visualstudio.com/items?itemName=shengchen.vscode-checkstyle), visit its [GitHub Repository](https://github.com/jdneo/vscode-checkstyle). \ No newline at end of file diff --git a/docs/java/java-faq.md b/docs/java/java-faq.md new file mode 100644 index 0000000000000000000000000000000000000000..d2b3a18a3886548ab6b0c53d900ca0ae0674dad7 --- /dev/null +++ b/docs/java/java-faq.md @@ -0,0 +1,56 @@ +--- +Order: 11 +Area: java +TOCTitle: FAQ +ContentId: 2ad03b46-0779-4c9a-897e-6e6b628f598a +PageTitle: Java on Visual Studio Code FAQ and Wiki +DateApproved: 1/2/2019 +MetaDescription: Java on Visual Studio Code Frequent Asked Questions and Troubleshooting Guide +--- +# Frequent Asked Questions + +Thanks for your interest in Java on Visual Studio Code! This FAQ will hopefully answer some of the questions you may have. + +## Are these Java extensions open source? + +Yes. All the [Java Extensions](/docs/java/extensions.md) provided by Red Hat, Microsoft, and Pivotal are open source, as well as most extensions supported by the community. You can find their corresponding repositories on GitHub from the Marketplace pages. + +## Are there any other feature coming to Java on Visual Studio Code? + +Definitely. We use GitHub issues to track incoming requests and planned work for each of our extensions. Currently we're working on adding more refactoring and linting features to enhance the editing productivity, as well as some performance improvements to make it even faster. + +Most of our work is collected from and prioritized by customer feedback. If you're interested in providing your thoughts, you can either go directly to our project repositories to submit a new issue or use this [Survey Link](https://www.research.net/r/vscodejava) to share your thoughts. + +We do have limited capacity within the team and we'd really like to encourage more contributions from the great Java community. If you're passionate about your idea and would like to help fellow Java developers, you're welcome to join us! Some areas worth considering including Gradle support, code analysis and test coverage tools, profiler, and additional framework support including DropWizard, JavaFX, JPA, Play, Akka, OSGi. + +## Can I use keyboard shortcuts from other IDE? + +Sure. [Keymap extensions](/docs/getstarted/keybindings.md#keymap-extensions) in VS Code modify the VS Code shortcuts to match those of other editors. You can find [IntelliJ IDEA Keybindings](https://marketplace.visualstudio.com/items?itemName=k--kato.intellij-idea-keybindings), [Eclipse Keymap](https://marketplace.visualstudio.com/items?itemName=alphabotsec.vscode-eclipse-keybindings) as well as keymaps for other popular editors in [Keymaps category](https://marketplace.visualstudio.com/search?target=VSCode&category=Keymaps&sortBy=Downloads) of extensions in the Marketplace. + +## Where can I find the latest progress of Java support on Visual Studio Code? + +We're currently publishing our updates at [The Visual Studio Blog](https://devblogs.microsoft.com/visualstudio/tag/java/), which will report all our major features and improvements. + +While you're using Java within VS Code, you might also see a *Release Notes* once you update the [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack). That will give you an overview on the notable updates included in the extensions. + +## Will this be available for Visual Studio? + +Currently we don't plan to extend the Java support to Visual Studio. There's already great IDEs for Java and we're focusing on VS Code to provide a lightweight experience in a polyglot editor. + +## Does VS Code Java support other display languages? + +Currently we support Chinese in addition to English for a few extensions including [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug), [Java Test Runner](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-test), [Maven for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-maven), [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency). To learn how to switch the VS Code display language, see [Display Languages](/docs/getstarted/locales.md). + +You can contribute to the extension repositories if you're interested in additional display language support. + +## How to troubleshoot and contribute to the Java Language Server + +You can visit the [Java for Visual Studio Code wiki](https://github.com/redhat-developer/vscode-java/wiki) to find answers regarding: + +1. ["Classpath is incomplete" warning](https://github.com/redhat-developer/vscode-java/wiki/%22Classpath-is-incomplete%22-warning) +2. [Annotation Processing support for Maven projects](https://github.com/redhat-developer/vscode-java/wiki/Annotation-Processing-support-for-Maven-projects) +3. [Contribute a Java extension](https://github.com/redhat-developer/vscode-java/wiki/Contribute-a-Java-Extension) +4. [Formatter settings](https://github.com/redhat-developer/vscode-java/wiki/Formatter-settings) +5. [Lombok Support](https://github.com/redhat-developer/vscode-java/wiki/Lombok-support) +6. [Using a Proxy](https://github.com/redhat-developer/vscode-java/wiki/Using-a-Proxy) +7. [Troubleshooting](https://github.com/redhat-developer/vscode-java/wiki/Troubleshooting) \ No newline at end of file diff --git a/docs/java/java-project.md b/docs/java/java-project.md new file mode 100644 index 0000000000000000000000000000000000000000..1bd80e70ac74b95980c1e986ef4aaf299758d3a4 --- /dev/null +++ b/docs/java/java-project.md @@ -0,0 +1,111 @@ +--- +Order: 5 +Area: java +TOCTitle: Project Management +ContentId: 251cba68-c77f-4ac6-a5de-1fab8dcca867 +PageTitle: Maven Support, Java Package, and Dependency Management in Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: Maven Support, Java Package and Dependency Management in Visual Studio Code +MetaSocialImage: +--- + +# Java Project Management in VS Code + +This document will give you an overview of how to use the [Maven for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-maven) and [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) extensions to manage your projects within Visual Studio Code. + +## Maven + +[Maven](http://maven.apache.org/) is a software tool that helps you manage Java projects and automate application builds. The [Maven for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-maven) extension for Visual Studio Code provides fully integrated Maven support, allowing you to explore Maven projects, execute Maven commands, and perform the goals of build lifecycle and plugins. + +### Exploring Maven project + +Once a Maven project is loaded, the extension will be activated and it will automatically scan for `pom.xml` files in your workspace and displays all Maven projects and their modules in the side bar. + +![Maven Explorer](images/java-project/maven-explorer.png) + +### Working with POM.xml + +The extension provides code snippets and auto completion for adding Maven dependencies based on local Maven repositories. See how easy it is to add a new dependency to your `pom.xml` with those convenient features. + +![POM Editing Assistance](images/java-project/maven-pom-editing.gif) + +The extension also enables you to generate effective POM. + +![Generate Effective POM](images/java-project/maven-effective-pom.gif) + +### Execute Maven commands and goals + +By right-clicking each Maven project in the explorer, you can conveniently run Maven goals. + +![Run Maven Goal](images/java-project/maven-run.gif) + +The extension also preserves the history of goals for each project, so you can quickly rerun the previous command, which is useful when you're running a long custom goal. + +There are two way to rerun a goal: + +1. Command Palette > Select **Maven: History** > Select a project > Select command from the history. +2. Right-click a project > Click **History** > Select command from history. + +![Rerun history](images/java-project/maven-history.gif) + +For each plug-in you use with your project, the extension also provides you an easy way to access the goals within each plugin. + +![Run plug-in goal](images/java-project/maven-plugin-goal.gif) + +### Generate project from maven Archetype + +Another handy feature provided by this extension is to generate a Maven project from [Archetype](https://maven.apache.org/guides/introduction/introduction-to-archetypes.html). The extension loads archetypes listed in local/remote catalogs. After selection, the extension sends `mvn archetype:generate -D...` to the terminal. + +There are two ways to generate a Maven project: + +1. From the Command Palette, select **Maven: Generate from Maven Archetype**. +2. Right-click on a folder and select **Generate from Maven Archetype**. + +![Generate Project from Archetype](images/java-project/maven-archetype.gif) + +### Additional resources + +Visit the [GitHub Repo](https://github.com/Microsoft/vscode-maven) of the Maven extension for additional [configurations](https://github.com/Microsoft/vscode-maven/tree/master#additional-configurations) and a [troubleshooting guide](https://github.com/Microsoft/vscode-maven/blob/master/Troubleshooting.md). + +In addition to Maven, there's also a [Bazel extension](https://marketplace.visualstudio.com/items?itemName=BazelBuild.vscode-bazel) if you use Bazel to build and test your project. + +## Project management + +Project Management in Visual Studio Code is provided by the [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) extension. This extension has many features including creating projects as well as viewing the package structure of the project and its dependencies. + +### Create project + +In addition to creating a project through Maven Archetype, you can also use the following command to create a simple Java project: Command Palette > select **Java: Create Java Project**. + +![Creating Project](images/java-project/create-project.gif) + +If you're creating a Spring Boot project, you can also use the [Spring Initializr](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-initializr) extension, see [Spring Boot in Visual Studio Code](/docs/java/java-spring-boot.md). + +### Package and dependency view + +The extension also has a hierarchy view of your project and dependencies, which supplements the file view and outline provided by Visual Studio Code, so you don't need to expand multiple subfolders to just view your Java package. + +![Package Viewer](images/java-project/package-viewer.gif) + +![Hierarchical View](images/java-project/hierarchical.gif) + +### Multiple source folders + +If you have multiple sub-folders that have source code for your project, you can easily add these folders to source path, then all the code inside will be correctly compiled. + +![Multiple source folders](images/java-project/multiple-source.gif) + +### Standalone Java file support + +Visual Studio Code also supports Java files without a project. The solution is folder-based, so all you need to do is open a folder with Visual Studio Code, and all the Java files within the folder will be properly compiled with all language features available. You can also run and debug standalone files. + +![Standalone Files](images/java-project/standalone.gif) + +## Next steps + +Read on to find out more about: + +* [Java Editing](/docs/java/java-editing.md) - Explore the editing features for Java in VS Code. +* [Java Debugging](/docs/java/java-debugging.md) - Find out how to debug your Java project with VS Code. +* [Java Testing](/docs/java/java-testing.md) - Use VS Code for your JUnit and TestNG cases. +* [Java Extensions](/docs/java/extensions.md) - Learn about more useful Java extensions for VS Code. diff --git a/docs/java/java-spring-boot.md b/docs/java/java-spring-boot.md new file mode 100644 index 0000000000000000000000000000000000000000..cd02fb92ce510be0f3bacf82425fc9516fb8001a --- /dev/null +++ b/docs/java/java-spring-boot.md @@ -0,0 +1,116 @@ +--- +Order: 7 +Area: java +TOCTitle: Spring Boot +ContentId: d37118cf-1b5b-4aee-9727-52fcfcac16bd +PageTitle: Spring Boot support in Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: Spring Boot extensions for Java developer using Visual Studio Code editor. +--- + +# Spring Boot in Visual Studio Code + +Visual Studio Code is an ideal lightweight development environment for Spring Boot application developers and there are several useful VS Code extensions including: + +* [Spring Boot Tools](https://marketplace.visualstudio.com/items?itemName=Pivotal.vscode-spring-boot) +* [Spring Initializr](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-initializr) +* [Spring Boot Dashboard](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-boot-dashboard) + +## Prerequisites + +A working Java environment with essential extensions installed is needed, including +* [Java Development Kit (JDK)](http://www.oracle.com/technetwork/java/javase/downloads/), version 1.8. +* [Apache Maven](https://maven.apache.org/), version 3.0 or later. +* [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack) + +For more details, please refer to [Java Tutorial](/docs/java/java-tutorial.md#_before-you-begin) + +## Create the project + +The [Spring Initializr](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-initializr) extension allows you to search for dependencies and generate new Spring Boot projects. + +To install, launch VS Code and from the Extensions view (`kb(workbench.view.extensions)`), search for `vscode-spring-initializr`. + +Once you have the extension installed, open the **Command Palette** (`kb(workbench.action.showCommands)`) and type `Spring Initializr` to start generating a Maven or Gradle project and then follow the wizard. + +![Spring Initializr](images/java-spring-boot/spring-initializr.gif) + +## Edit the project + +The [Spring Initializr](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-initializr) extension allows you to edit dependencies after generating a new Spring Boot project. + +Navigate to your `pom.xml` file and right-click to select `Edit starters`. The **Command Palette** will show the dependencies you already have beginning with a `√` . You can search for other dependencies you want to add to your project. Or you can click on the existing dependencies to remove them. + +![Spring Initializr-edit](images/java-spring-boot/spring-initializr-edit.gif) + +## Develop the application + +The [Spring Boot Tools](https://marketplace.visualstudio.com/items?itemName=Pivotal.vscode-spring-boot) extension includes rich language support for working with Spring Boot `application.properties`, `application.yml`, and `.java` files. + +The extension supports quick navigate through source code, smart code completions, quick access to running apps, live application information, and code templates. Similar code completion and validation features are also available for `.properties` and `.yml` files. + +![Spring code editing](images/java-spring-boot/spring-code-edit.gif) + +## Run the application + +In addition to click `kb(workbench.action.debug.start)` to run your application, there's another convenient extension [Spring Boot Dashboard](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-boot-dashboard) with which you can view and manage all available Spring Boot projects in your workspace as well as quickly start, stop, or debug your project. + +![Spring Dashboard](images/java-spring-boot/spring-dashboard.gif) + +## Connect with data services + +[Azure Cosmos DB](https://docs.microsoft.com/azure/cosmos-db/introduction) is a globally distributed database service that allows developers to work with data using a variety of standard APIs, such as SQL, MongoDB, Cassandra, Graph, and Table. + +The [Spring Boot Starter](https://docs.microsoft.com/java/azure/spring-framework/configure-spring-boot-starter-java-app-with-cosmos-db) makes it easy to store data in and retrieve data from your Azure Cosmos DB with SQL API. + +Before running this sample on [Azure](https://azure.microsoft.com), you need to have an Azure subscription. + +If you don't have an Azure subscription, you can sign up for a [free Azure account](https://azure.microsoft.com/pricing/free-trial/): + +Create your free Azure account + +### Create an Azure Cosmos DB entity on Azure + +1. Go to [Azure portal](https://portal.azure.com/) and click the '+' to **Create a resource**. +2. Click **Databases**, and then click **Azure Cosmos DB** to create your database. +3. Select **SQL (Document DB) API** and type in other information for your database. +4. Navigate to the database you have created, click **Keys**, and copy your **URI** and **PRIMARY KEY** for your database. + +### Config your project + +1. You can start from the [Spring Data Azure Cosmos DB Sample Project](https://github.com/Microsoft/azure-spring-boot/tree/master/azure-spring-boot-samples/azure-cosmosdb-spring-boot-sample). + +2. Navigate to `src/main/resources` and open `application.properties`. Replace below properties in `application.properties` with information of your database. + + ```bash + azure.documentdb.uri=your-documentdb-uri + azure.documentdb.key=your-documentdb-key + azure.documentdb.database=your-documentdb-databasename + ``` + +### Run and debug the application + +You can press `kb(workbench.action.debug.start)` to run your application. To check the result, open [Azure portal](https://portal.azure.com/) and access your Cosmos DB. Click **Data Explorer**, and next choose **Documents**. You will see data being shown if it is successfully written into Cosmos DB. You can also browse your data entries in Cosmos DB with [Azure Cosmos DB Extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb). + +After setting a breakpoint (`kb(editor.debug.action.toggleBreakpoint)`) in your source code, refresh your browser to hit the breakpoint. Details about debugging can be found in [Java Debugging](/docs/java/java-debugging.md) + +Alternatively, you can also use Maven to package and run your project as steps below: + +1. Navigate to the directory `azure-spring-boot` and run the command. + + ```bash + mvn install + ``` + +2. Navigate to the directory `azure-documentdb-spring-boot-sample` and run the command. + + ```bash + mvn package + java -jar target/azure-documentdb-spring-boot-sample-0.0.1-SNAPSHOT.jar + ``` + +## Next steps + +* To deploy your web app, see the [Deploy a Java Application to Azure](/docs/java/java-webapp.md) tutorial. +* To containerize a web app and deploy as a Docker container, check out the [Working with Docker](/docs/azure/docker.md). +* To learn more about Java Debugging features, see [Java Debugging Tutorial](/docs/java/java-debugging.md). \ No newline at end of file diff --git a/docs/java/java-testing.md b/docs/java/java-testing.md new file mode 100644 index 0000000000000000000000000000000000000000..a5381d8fb2363c0f728bc1a097d3a3892ab783dd --- /dev/null +++ b/docs/java/java-testing.md @@ -0,0 +1,56 @@ +--- +Order: 4 +Area: java +TOCTitle: Unit Testing +ContentId: 82be3b78-2c09-4571-abec-69f95f111e0f +PageTitle: Java Unit Tests in Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: See how you can test your Java code in Visual Studio Code. +MetaSocialImage: +--- + +# Testing Java with Visual Studio Code + +Testing Java in Visual Studio Code is enabled by the [Java Test Runner](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-test) extension. It's a lightweight extension to run and debug Java test cases. The extension supports the following test frameworks: + +- JUnit 4 (v4.8.0+) +- JUnit 5 (v5.1.0+) +- TestNG (v6.8.0+) + +>**Note**: More information about the test frameworks can be found at [JUnit](https://junit.org/) and [TestNG](https://testng.org/). + +The [Java Test Runner](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-test) works with the [Language Support for Java by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) and [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) extensions to provide the following features: + +- Run test cases +- Debug test cases +- View test report +- View tests in Test Explorer + +Once the test runner is activated, you will find **Run|Debug** on the CodeLens of your test functions. Click on the CodeLens to run the individual test case. You can also access and run a group of test cases from the Test Explorer. For more information on debugging test cases, see [Debugging Java](/docs/java/java-debugging.md). + +Here's a brief session with TestNG: + +![Test Explorer with TestNG](images/java-testing/testng.gif) + +And with JUnit5: + +![Test Explorer with JUnit5](images/java-testing/test-junit5.gif) + +The JUnit 5 support also covers frequently used annotations such as `@DisplayName` and `@ParameterizedTest` + +![DisplayName](images/java-testing/displayname.png) + +![ParameterizedTest](images/java-testing/parameterizedtest.png) + +Visit the [GitHub repository](https://github.com/Microsoft/vscode-java-test) of the [Java Test Runner](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-test) for more details on commands and settings. + +You can also view the Test Report and navigate to source from there. + +![Test Report](images/java-testing/report.gif) + +## Next steps + +Read on to find out about: + +* [Debugging](/docs/java/java-debugging.md) - Find out how to debug your Java project with VS Code. +* [Java Extensions](/docs/java/extensions.md) - Learn about more useful Java extensions for VS Code. diff --git a/docs/java/java-tomcat-jetty.md b/docs/java/java-tomcat-jetty.md new file mode 100644 index 0000000000000000000000000000000000000000..5cfc8243c7587b7b1fd86410316b9e289e54fbc0 --- /dev/null +++ b/docs/java/java-tomcat-jetty.md @@ -0,0 +1,44 @@ +--- +Order: 6 +Area: java +TOCTitle: Tomcat and Jetty +ContentId: 4f5e169c-d91d-46b7-8c36-b695b5862313 +PageTitle: Tomcat and Jetty support in Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: Tomcat and Jetty extensions for Java developer using Visual Studio Code. +--- + +# Tomcat and Jetty support in VS Code + +Although Visual Studio Code is a code editor-centric development tool, we know that for certain Java workloads, server integration is very useful. With Visual Studio Code, you can find extensions for popular application servers, for example [Tomcat](http://tomcat.apache.org/) and [Jetty](http://www.eclipse.org/jetty/), which are helpful when working with those servers locally. + +For [Spring Boot Dashboard](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-boot-dashboard), see [Spring Boot in Visual Studio Code](/docs/java/java-spring-boot.md). + +## Tomcat + +With the [Tomcat](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) extension, you can manage all your local Tomcat servers within the editor and easily debug and run your `war` package on Tomcat and link Tomcat into your workspace. + +![Tomcat](images/java-tomcat-jetty/tomcat.gif) + +You can also create a new Tomcat server from the explorer using the **Add** button and run a `war` package on it. You can also create the server during the deployment. + +![Create Server](images/java-tomcat-jetty/tomcat-create-server.gif) + +For running and debugging a package, you can right-click a server to select a `war` package to debug. More details could be found in the [GitHub repository](https://github.com/adashen/vscode-tomcat) of the [Tomcat](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) extension. + +## Jetty + +The [Jetty for Java](https://marketplace.visualstudio.com/items?itemName=SummerSun.vscode-jetty) extension for Visual Studio Code makes it much easier for you to run and deploy your `war` package, operate your Jetty Server, and interact with your application within the editor. + +The extension includes the following features: + +* Add Jetty Server from download directory +* Start/Restart/Stop/Delete Jetty Server +* Run/Debug/Delete `war` package +* Reveal `war` package in file explorer +* Open Server homepage +* Open `war` package homepage + +![Jetty](images/java-tomcat-jetty/jetty.gif) + +More details could be found in the [GitHub repository](https://github.com/summersun/vscode-jetty) of the [Tomcat](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) extension. diff --git a/docs/java/java-tutorial.md b/docs/java/java-tutorial.md new file mode 100644 index 0000000000000000000000000000000000000000..ac8b27f0e85bdfc9e1171e3eadcd762a46eb70cd --- /dev/null +++ b/docs/java/java-tutorial.md @@ -0,0 +1,85 @@ +--- +Order: 1 +Area: java +TOCTitle: Java Tutorial +ContentId: 12d8264b-643f-4745-a7ea-8433dedb1331 +PageTitle: Writing Java with Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: Java tutorial showing basic Java language support in the Visual Studio Code editor +--- + +# Writing Java with Visual Studio Code + +This tutorial shows you how to write and run a simple Hello World program in Java with Visual Studio Code. It also covers a few advanced features, which you can explore by reading other documents in this section. + +## Before you begin + +Before going through this tutorial, you must have the Java SE Development Kit (JDK) and Apache Maven build tools on your local development environment. If you don't have them installed, you can do so now. + +Download and install the Java SE Development Kit (JDK). Java support on Visual Studio Code works with all major Java version up to 11, below is a link for version 8: + +Download JDK + +>**Note**: The `JAVA_HOME` environment variable must be set to the install location of the JDK to complete this tutorial. + +Download Apache Maven version 3 or greater: + +Download Apache Maven + +Install Apache Maven for your local development environment: + +Install Apache Maven + +## Install Visual Studio Code and Java Extensions + +>**Note**: You can install Visual Studio Code from [https://code.visualstudio.com](https://code.visualstudio.com/). + +To help set up Java on VS Code, there is the Microsoft [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack), which contains these popular extensions: + +1. [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) +2. [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) +3. [Java Test Runner](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-test) +4. [Maven for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-maven) +5. [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) + +Install the Java Extension Pack + +You can also select which extensions you would like to install separately. For this tutorial, only [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) and [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) are needed. + +## Create the program + +Create a folder for your Java program and open the folder with Visual Studio Code. Within Visual Studio Code, you can then create a new file `Hello.java`. When you open that file, the Java Language Server will automatically be activated as you can see a rocket icon on the right of the Status bar. When it finishes loading, you will see a thumbs up icon instead. + +![Create Project](images/java-tutorial/create-file.gif) + +Visual Studio Code also supports more complex Java projects, see [Project Management](/docs/java/java-project.md). + +>**Note**: The Java Language Server might not work properly if you open a standalone Java file in Visual Studio Code without opening its folder. + +## Editing code + +In Visual Studio Code, you can easily use code snippets to scaffold your class and method. VS Code also provides IntelliSense for code completion. + +![Edit Code](images/java-tutorial/edit-code.gif) + +You can also use various refactor methods within the editor. To learn more about Java code editing in Visual Studio Code, see [Java Editing](/docs/java/java-editing.md). + +## Running and debugging your program + +It is easy to run and debug Java in Visual Studio Code. You can either click `kb(workbench.action.debug.start)` or use the **Run|Debug** CodeLens options. Just set a breakpoint and you can see all your variables and threads in the Debug view. + +![Run and Debug](images/java-tutorial/run-debug.gif) + +The debugger also supports advanced features such as Hot Code replacement and conditional breakpoints. For more information, see [Java Debugging](/docs/java/java-debugging.md). + +## More features + +Now you've seen how easy it is to write a simple Java program with Visual Studio Code. The editor has much more capability to offer for your Java workload. + +* [Editing Java](/docs/java/java-editing.md) explains how to navigate and edit Java in more details. +* [Debugging](/docs/java/java-debugging.md) illustrates all the key features provided for Java debug. +* [Testing](/docs/java/java-testing.md) provides comprehensive supports for JUnit and TestNG framework. +* [Java Project Management](/docs/java/java-project.md) shows you how it provides you a project view and works with Maven. +* [Spring Boot Support](/docs/java/java-spring-boot.md) and [Tomcat and Jetty](/docs/java/java-tomcat-jetty.md) demonstrate great support for Spring Boot, Tomcat, and Jetty. + +To learn how to work with Java Web App in VS Code, read [Java Web App](/docs/java/java-webapp.md). diff --git a/docs/java/java-webapp.md b/docs/java/java-webapp.md new file mode 100644 index 0000000000000000000000000000000000000000..246f0ec096b54ed0eccf39416446f991419848e6 --- /dev/null +++ b/docs/java/java-webapp.md @@ -0,0 +1,143 @@ +--- +Order: 8 +Area: java +TOCTitle: Java Web App +ContentId: 98ddf1d3-6a8e-4b0f-a44d-e57cfdf2348c +PageTitle: Build and Deploy Java Web Apps to the cloud with Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: Java web app tutorial showing how to build and deploy a Java web app to Azure with Visual Studio Code +--- + +# Java Web Apps with Visual Studio Code + +This tutorial shows you how to create a Java web application with Visual Studio Code. You'll learn how to run, debug, and edit the Java web app locally and eventually on the cloud. + +## Scenario + +A simple Spring Boot Getting Started web app + +![Greeting from Java](images/java-webapp/greeting-from-spring.png) + +## Before you begin + +Before running and deploying this sample, you must have the Java SE Development Kit (JDK) and Apache Maven build tools on your local development environment. If you don't have, please install them. + +Download and install the Java SE Development Kit (JDK), version 8: + +Download JDK + +>**Note**: The `JAVA_HOME` environment variable must be set to the install location of the JDK to complete this tutorial. + +Download Apache Maven version 3 or greater: + +Download Apache Maven + +Install Apache Maven for your local development environment: + +Install Apache Maven + +## Download and test the Spring Boot app + +Clone the [Spring Boot Getting Started](https://github.com/spring-guides/gs-spring-boot) sample project to your local machine. You can clone a Git repository with the **Git: Clone** command in the **Command Palette** (`kb(workbench.action.showCommands)`). Paste `https://github.com/spring-guides/gs-spring-boot.git` as the URL of the remote repository and then decide the parent directory under which to put the local repository. After that, open the cloned repository in VS Code by navigating to the repository folder and typing `code .`. + +>**Note**: You can install Visual Studio Code from [https://code.visualstudio.com](https://code.visualstudio.com/) and Git from [https://git-scm.com](https://git-scm.com/). + +![Clone Spring Repository](images/java-webapp/clone-repository.gif) + +From within VS Code, navigate to the `complete` folder that contains the project which is ready to run. Open any of the Java files in the repository (for example `complete\src\main\java\hello\Application.java`). If you don't have the Java language extensions installed for VS Code, you will be prompted to install the Microsoft [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack). Follow the instructions and reload VS Code after the installation. + +![Install Java Extensions](images/java-webapp/install-extensions.gif) + +Once you have the Java Extension Pack installed, it will automatically build the project for you (this may take several minutes). You can run the application within VS Code by pressing `kb(workbench.action.debug.start)` and selecting the **Java** environment. The Java Debug extension will generate a debugging configuration file `launch.json` for you under a `.vscode` folder in your project. You can see build progress in the VS Code Status Bar and when everything is finished, the final active debug configuration is displayed. + +![debug configuration in the Status Bar](images/java-webapp/debugging-status-bar.png) + +You can learn more about how VS Code launches your application in Debugging [Launch Configurations](/docs/editor/debugging.md#launch-configurations). Press `kb(workbench.action.debug.start)` again to launch the debugger. + +![Run Spring Boot](images/java-webapp/run-spring-boot.gif) + +Test the web app by browsing to `http://localhost:8080` using a web browser. You should see the following message displayed: "Greetings from Spring Boot!". + +![Greeting from Spring](images/java-webapp/greeting-from-spring.png) + +## Make a change + +Let's now edit `HelloController.java` to change "Greetings from Spring Boot!" to something else like "Hello World". VS Code provides a great editing experience for Java, check out [Editing and Navigating Code](/docs/languages/java.md#editing-and-navigating-code) to learn about VS Code's editing and code navigation features. + +Click the **Restart** button on the top of the editor to relaunch the app and see result by reloading the browser. + +![Restart Application](images/java-webapp/restart-application.png) + +## Debug the application + +Set a breakpoint (`kb(editor.debug.action.toggleBreakpoint)`) in the application source code, and reload your browser to hit the breakpoint. + +![Debug Application](images/java-webapp/debugging.png) + +If you would like to learn more about debugging Java with VS Code, you can read [Java Debugging](/docs/java/java-debugging.md). + +Congratulations, you have your first Spring Boot web app running locally! Read on to learn how to host it in the cloud. + +## Deploy Web Apps to the cloud + +We just built a Java web application and ran it locally. Now you will learn how to deploy from Visual Studio Code and run it on [Azure](https://azure.microsoft.com) in the cloud. + +If you don't have an Azure subscription, you can sign up for a [free Azure account](https://azure.microsoft.com/pricing/free-trial/). +Create your free Azure account + +### Install the Azure App Service extension + +The [Azure App Service](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) extension is used to create, manage, and deploy to Azure App Service with key features including: + +- Create new Azure Web App/Deployment Slot +- Deploy to Azure Web App/Deployment Slot +- Start, stop, and restart the Azure Web App/Deployment Slot +- View a Web App's log files +- Swap Deployment Slots + +To install the Azure App Service extension, open the Extensions view (`kb(workbench.view.extensions)`) and search for `azure app service` to filter the results. Select the Microsoft [Azure App Service](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) extension. For a more command-line Maven-centric experience, you can also check out the [Maven plugin for Azure App Service Linux tutorial](https://docs.microsoft.com/azure/app-service/containers/quickstart-java). + +### Create a new Web App + +Once the extension is installed, you can take the following steps to create a new Web App. + +1. Click **Create New Project** button on the **APP SERVICE** Explorer view. +2. Select a subscription. +3. Enter a unique name for the new Web App. +4. Select a location for the new Web App. +5. Select the OS as `Linux`. +6. Select the runtime of the Web App, for example `Tomcat 8.5 (JRE8)`. + +![Create a Web App](images/java-webapp/create-webapp.png) + +### Build and deploy to a Web App + +The deploy process leverages the [Azure Account](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account) extension (installed along with the Azure Functions extension as a dependency) and you need to sign in with your Azure subscription. If you do not have an Azure subscription, [sign up today](https://azure.microsoft.com//free/?b=16.48) for a free 30 day account and get $200 in Azure Credits to try out any combination of Azure services. + +To log into Azure, run **Azure: Sign In** from the **Command Palette** (`kb(workbench.action.showCommands)`). You can then sign into your account using the **Device Login** flow. Click on **Copy & Open** to open your default browser. + +![Azure sign in code](images/java-webapp/devicelogin.png) + +Paste in the access code and continue the sign in process. + +![Azure Device Login](images/java-webapp/devicelogin2.png) + +Once you have signed in, you can open the command prompt or terminal window and build the project using Maven commands. This will generate a new `name.war` or `name.jar` file in the `target` directory. + +```bash +mvn clean package +``` +After building the project, open the `target` directory in VS Code Explorer. Right-click on the `name.war` or `name.jar` file and choose **Deploy to Web App**, and follow the prompts to choose the Web App for your deployment. + +![Deploy to Web App](images/java-webapp/deploy-webapp.png) + +Open the **Output** window in VS Code to view the deployment logs. Once the deployment is completed, it will print out the URL for your Web App. Click the link to open it in a browser, you can see the web app running on Azure! + +![Greeting from Spring Boot](images/java-webapp/greeting.png) + +> **Note:** For more advanced features of App Service, you can check out the [Azure App Service](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) extension. + +## Next steps + +* To containerize and deploy a web application, check out the [Docker Container Tutorial](/docs/azure/docker.md). +* To learn more about Java Debugging features, see the [Java Debugging Tutorial](/docs/java/java-debugging.md). diff --git a/docs/languages/cpp.md b/docs/languages/cpp.md new file mode 100644 index 0000000000000000000000000000000000000000..a349e46b5200a9754d7679ccde66486fed214314 --- /dev/null +++ b/docs/languages/cpp.md @@ -0,0 +1,398 @@ +--- +Order: 8 +Area: languages +TOCTitle: C++ +ContentId: D06C8C5C-2D3A-4B2E-B31F-12F1907E6402 +PageTitle: C++ programming with Visual Studio Code +DateApproved: 8/22/2017 +MetaDescription: Find out how to get the best out of Visual Studio Code and C++. +MetaSocialImage: images/cpp/languages_cpp.png +--- +# C/C++ for Visual Studio Code (Preview) + +C/C++ support for Visual Studio Code is provided by a [Microsoft C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) to enable cross-platform C and C++ development using VS Code on Windows, Linux, and macOS. The extension is still in preview and our focus is code editing, navigation, and debugging support for C and C++ code everywhere that VS Code runs. + +![cpp hero](images/cpp/cpp-hero.png) + +If you just want a lightweight tool to edit your C++ files, Visual Studio Code is a great choice but if you want the best possible experience for your existing Visual C++ projects or debugging on Windows, we recommend you use a version of the Visual Studio IDE such as [Visual Studio Community](https://visualstudio.microsoft.com/vs/community). + +If you run into any issues or have suggestions for the Microsoft C/C++ extension, please file [issues and suggestions on GitHub](https://github.com/Microsoft/vscode-cpptools/issues). If you haven't already provided feedback, please take this [quick survey](https://www.research.net/r/VBVV6C6) to help shape this extension for your needs. + +## Getting Started + +**To install the Microsoft C/C++ extension:** + +* Open VS Code. +* Click the Extensions View icon on the Sidebar. +* Search for `c++`. +* Click **Install**, then click **Reload**. + +![cpp extension](images/cpp/cpp-extension.png) + +With the C/C++ extension installed, open a folder that contains your C/C++ source code. VS Code will place various settings files into a `.vscode` subfolder. + +**Note**: The C/C++ extension does not include a C++ compiler or debugger. You will need to install these tools or use those already installed on your computer. Popular C++ compilers are [mingw-w64](http://www.mingw-w64.org/) for Windows, Clang for [XCode](https://developer.apple.com/xcode/) for macOS, and [GCC](https://gcc.gnu.org/) on Linux. Make sure your compiler executable is in your platform path so the extension can find it. The extension also supports the [Windows Subsystem for Linux](https://github.com/Microsoft/vscode-cpptools/blob/master/Documentation/LanguageServer/Windows%20Subsystem%20for%20Linux.md). + +### Configuring IntelliSense + +The extension will attempt to determine your folder's basic configuration info based on compilers it finds on your system. If for any reason, that configuration is incomplete, you can generate a `c_cpp_properties.json` file by running the **C/Cpp: Edit configurations** command from the **Command Palette** (`kb(workbench.action.showCommands)` and add the missing information. + +If a `#include` file or one of its dependencies cannot be found, you can also click on the red squiggles under the include statements to view suggestions for how to update your configuration. + +![browse path light bulb](images/cpp/cpp-lightbulb.png) + +This will generate a `c_cpp_properties.json` file that allows you to add additional paths and defines to properly enable code navigation and auto-completion. + +Below you can see that the MinGW C++ compiler has been set as the default compiler for Windows. The extension will use that information to determine the system include path and defines so that they don't need to be added to `c_cpp_properties.json`. + +```json +{ + "name": "Win32", + "includePath": [ + "${workspaceFolder}" + ], + "defines": [ + "_DEBUG", + "UNICODE" + ], + "compilerPath": "C:\\mingw-w64\\bin\\gcc.exe", + "intelliSenseMode": "clang-x64", + "browse": { + "path": [ + "${workspaceFolder}" + ], + "limitSymbolsToIncludedHeaders": true, + "databaseFilename": "" + } +} +``` + +### Building your code + +**If you want to build your application from VS Code, you will need to generate a `tasks.json` file:** + +* Open the **Command Palette** (`kb(workbench.action.showCommands)`). +* Select the **Tasks: Configure Task** command, click **Create tasks.json file from templates**, and you will see a list of task runner templates. +* Select **Others** to create a task which runs an external command. +* Change the `command` to the command line expression you use to build your application (for example `g++`). +* Add any required args (for example `-g` to build for debugging). +* You can also change the `label` to be more descriptive. + +You should now see a `tasks.json` file in your workspace `.vscode` folder that looks something like: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "build hello world", + "type": "shell", + "command": "g++", + "args": [ + "-g", "helloworld.cpp" + ] + } + ] +} +``` + +If you'd like to be able to build your application with **Tasks: Run Build Task** (`kb(workbench.action.tasks.build)`), you can add it to the `build` group. + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "build hello world", + "type": "shell", + "command": "g++", + "args": [ + "-g", "helloworld.cpp" + ], + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} + +``` + +For more information on tasks, see [Integrate with External Tools via Tasks](/docs/editor/tasks.md). + +### Debugging your code + +**To enable debugging, you will need to generate a `launch.json` file:** + +* Navigate to the Debug view by clicking the Debug icon in the Sidebar. +* In the **Debug** view, click the **Configure** icon. +* Select `C++ (GDB/LLDB)` (to use GDB or LLDB) or `C++ (Windows)` (to use the Visual Studio Windows Debugger) from the **Select Environment** drop-down list. This creates a `launch.json` file for editing with two configurations: + * **C++ Launch** defines the properties for launching your application when you start debugging. + * **C++ Attach** defines the properties for attaching to a process that's already running. +* Update the `program` property with the path to the program you are debugging. +* If you want your application to build when you start debugging, add a `preLaunchTask` property with the name of the build task you created in `tasks.json` ("build hello world" in the example above). + +Below is an example using the MinGW GDB debugger: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "(gdb) Launch", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceFolder}/a.exe", + "args": [], + "stopAtEntry": false, + "cwd": "${workspaceFolder}", + "environment": [], + "externalConsole": true, + "MIMode": "gdb", + "miDebuggerPath": "C:\\mingw\\bin\\gdb.exe", + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + } + ], + "preLaunchTask": "build hello world" + } + ] +} +``` + +To learn more, see [Configuring launch.json for C/C++ debugging](https://github.com/Microsoft/vscode-cpptools/blob/master/launch.md). + +If you are debugging with GDB on Windows, see [Windows Debugging with GDB](#windows-debugging-with-gdb). + +## Editing Code + +### Code Formatting + +The C/C++ extension for Visual Studio Code supports source code formatting using [clang-format](https://clang.llvm.org/docs/ClangFormat.html) which is included with the extension. + +You can format an entire file with **Format Document** (`kb(editor.action.formatDocument)`) or just the current selection with **Format Selection** (`kb(editor.action.formatSelection)`) in right-click context menu. You can also configure auto-formatting with the following [settings](/docs/getstarted/settings.md): + +* `editor.formatOnSave` - to format when you save your file. +* `editor.formatOnType` - to format as you type (triggered on the `kbstyle(;)` character). + +By default, the clang-format style is set to "file" which means it looks for a `.clang-format` file inside your workspace. If the `.clang-format` file is found, formatting is applied according to the settings specified in the file. If no `.clang-format` file is found in your workspace, formatting is applied based on a default style specified in the `C_Cpp.clang_format_fallbackStyle` [setting](/docs/getstarted/settings.md) instead. Currently, the default formatting style is "Visual Studio" which is an approximation of the default code formatter in Visual Studio. + +The "Visual Studio" clang-format style is not yet an official OOTB clang-format style but it implies the following clang-format settings: + +```json +UseTab: (VS Code current setting) +IndentWidth: (VS Code current setting) +BreakBeforeBraces: AllMan +AllowShortIfStatementsOnASingleLine: false +IndentCaseLabels: false +ColumnLimit: 0 +``` + +If you'd like to use a different version of clang-format than the one that ships with the extension, you can use the `C_Cpp.clang_format_path` [setting](/docs/getstarted/settings.md) and set its value to the path where the clang-format binary is installed. + +For example, on the Windows platform: + +```json + "C_Cpp.clang_format_path": "C:\\Program Files (x86)\\LLVM\\bin\\clang-format.exe" +``` + +### Auto-Complete + +Auto-complete is powered by the same engine as Visual Studio. You will get the most relevant suggestions when your workspace is configured with all necessary include paths and defines (see the "Configuring IntelliSense" section above). + +## Navigating Code + +The source code navigation features provided by the C/C++ extension are powerful tools for understanding and getting around in your codebase. These features are powered by tags stored in an offline database of symbol information. With the C/C++ extension installed, this database is generated whenever a folder containing C++ source code files is loaded into VS Code. The database icon appears next to the active configuration name ("Win32" in the image below) while the tag-parser is generating this information. + +![The platform indicator during tag parsing](images/cpp/parsing.png) + +When the icon disappears, the source code symbols have been tagged in the offline database. + +### Specifying Additional Include Directories for Better Symbol Support + +To provide the best experience, the C/C++ extension for VS Code needs to know where it can find each header file referenced in your code. By default, the extension searches the current source directory, its sub-directories, and some platform-specific locations. If a referenced header file can't be found, VS Code displays a green squiggle underneath each #include directive that references it. + +To specify additional include directories to be searched, place your cursor over any #include directive that displays a green squiggle, then click the lightbulb action when it appears. This opens the file `c_cpp_properties.json` for editing; here you can specify additional include directories for each platform configuration individually by adding more directories to the 'browse.path' property. + +### Search for Symbols + +You can search for symbols in the current file or workspace to navigate your code more quickly. + +To search for a symbol in the current file, press `kb(workbench.action.gotoSymbol)`, then enter the name of the symbol you're looking for. A list of potential matches will appear and be filtered as you type. Choose from the list of matches to navigate to its location. + +![Searching the current file](images/cpp/filesearch.png) + +To search for a symbol in the current workspace, press `kb(workbench.action.showAllSymbols)`, then enter the name of the symbol. A list of potential matches will appear as before. If you choose a match that was found in a file that's not already open, the file will be opened before navigating to the match's location. + +![Searching in your workspace](images/cpp/workspacesearch.png) + +Alternatively, you can search for symbols by accessing these commands through the **Command Palette** if you prefer. Use **Quick Open** (`kb(workbench.action.quickOpen)`) then enter the '@' command to search the current file, or the '#' command to search the current workspace. `kb(workbench.action.gotoSymbol)` and `kb(workbench.action.showAllSymbols)` are just shortcuts for the '@' and '#' commands, respectively, so everything works the same. + +### Peek Definition + +You can take a quick look at how a symbol was defined by using the Peek Definition feature. This feature displays a few lines of code near the definition inside a peek window so you can take a look without navigating away from your current location. + +To peek at a symbol's definition, place your cursor on the symbol anywhere it's used in your source code and then press `kb(editor.action.peekDefinition)`. Alternatively, you can choose **Peek Definition** from the context menu (right-click, then choose **Peek Definition**). + +![Peek definition](images/cpp/peekdefn.png) + +Currently, the C/C++ extension doesn't parse code in a way that helps it distinguish between competing definitions based on how the symbol is used. These competing definitions arise when the symbol defines different things in different contexts, such as occurs with overloaded functions, classes and their constructors, and other situations. When this happens, each of the competing definitions are listed in the right-hand side of the peek window with the source code of the current selection displayed on the left. + +With the peek window open, you browse the list of competing definitions to find the one you're interested in. If you want to navigate to the location of one of the definitions just double-click the definition you're interested in, or by double-clicking anywhere in the source code displayed on the left-hand side of the peek window. + +### Go to Definition + +You can also quickly navigate to where a symbol is defined by using the Go to Definition feature. + +To go to a symbol's definition, place your cursor on the symbol anywhere it is used in your source code and then press `kb(editor.action.revealDefinition)`. Alternatively, you can choose **Go to Definition** from the context menu (right-click, then choose **Go to Definition**). When there's only one definition of the symbol, you'll navigate directly to its location, otherwise the competing definitions are displayed in a peek window as described in the previous section and you have to choose the definition that you want to go to. + +## Debugging + +After you have set up the basics of your debugging environment as specified in [Getting Started](/docs/languages/cpp.md#getting-started), you can learn more details about debugging C/C++ in this section. + +VS Code supports the following debuggers for C/C++ depending on the operating system you are using: + +* **Linux**: GDB +* **macOS**: LLDB or GDB +* **Windows**: the Visual Studio Windows Debugger or GDB (using Cygwin or MinGW) + +### Windows Debugging with GDB + +You can debug Windows applications created using Cygwin or MinGW by using VS Code. To use Cygwin or MinGW debugging features, the debugger path must be set manually in the launch configuration (`launch.json`). To debug your Cygwin or MinGW application, add the `miDebuggerPath` property and set its value to the location of the corresponding gdb.exe for your Cygwin or MinGW environment. + +For example: + +```json + "miDebuggerPath": "c:\\mingw\\bin\\gdb.exe" +``` + +Cygwin/MinGW debugging on Windows supports both attach and launch debugging scenarios. + +### Conditional Breakpoints + +Conditional breakpoints enable you to break execution on a particular line of code only when the value of the condition is true. To set a conditional breakpoint, right-click on an existing breakpoint and select **Edit Breakpoint**. This opens a small peek window where you can enter the condition that must evaluate to true in order for the breakpoint to be hit during debugging. + +![A conditional break](images/cpp/condbreak.png) + +In the editor, conditional breakpoints are indicated by a breakpoint symbol that has a black equals sign inside of it. You can place the cursor over a conditional breakpoint to show its condition. + +### Function Breakpoints + +Function breakpoints enable you to break execution at the beginning of a function instead of on a particular line of code. To set a function breakpoint, on the **Debug** pane right-click inside the **Breakpoints** section, then choose **Add Function Breakpoint** and enter the name of the function on which you want to break execution. + +### Expression Evaluation + +VS Code supports expression evaluation in several contexts: + +* You can type an expression into the **Watch** section of the **Debug** panel and it will be evaluated each time a breakpoint is hit. +* You can type an expression into the **Debug Console** and it will be evaluated only once. +* You can evaluate any expression that appears in your code while you're stopped at a breakpoint. + +Note that expressions in the **Watch** section take effect in the application being debugged; an expression that modifies the value of a variable will modify that variable for the duration of the program. + +### Multi-threaded Debugging + +The C/C++ extension for VS Code has the ability to debug multi-threaded programs. All threads and their call stacks appear in the **Call Stack** section: + +![Multi-threaded process](images/cpp/threads.png) + +### Memory Dump Debugging + +The C/C++ extension for VS Code also has the ability to debug memory dumps. To debug a memory dump, open your `launch.json` file and add the `coreDumpPath` (for GDB or LLDB) or `dumpPath` (for the Visual Studio Windows Debugger) property to the **C++ Launch** configuration, set its value to be a string containing the path to the memory dump. This will even work for x86 programs being debugged on an x64 machine. + +### Additional Symbols + +If there are additional directories where the debugger can find symbol files (for example, `.pdb` files for the Visual Studio Windows Debugger), they can be specified by adding the `additionalSOLibSearchPath` (for GDB or LLDB) or `symbolSearchPath` (for the Visual Studio Windows Debugger). + +For example: + +```json + "additionalSOLibSearchPath": "/path/to/symbols;/another/path/to/symbols" +``` + +or + +```json + "symbolSearchPath": "C:\\path\\to\\symbols;C:\\another\\path\\to\\symbols" +``` + +### Locate source files + +The source file location can be changed if the source files are not located in the compilation location. This is done by simple replacement pairs added in the `sourceFileMap` section. The first match in this list will be used. + +For example: + +```json +"sourceFileMap": { + "/build/gcc-4.8-fNUjSI/gcc-4.8-4.8.4/build/i686-linux-gnu/libstdc++-v3/include/i686-linux-gnu": "/usr/include/i686-linux-gnu/c++/4.8", + "/build/gcc-4.8-fNUjSI/gcc-4.8-4.8.4/build/i686-linux-gnu/libstdc++-v3/include": "/usr/include/c++/4.8" +} +``` + +### GDB, LLDB and MI Commands (GDB/LLDB) + +For the `C++ (GDB/LLDB)` debugging environment, you can execute GDB, LLDB and MI commands directly through the debug console with the `-exec` command, but be careful, executing commands directly in the debug console is untested and might crash VS Code in some cases. + +### Other Debugging Features + +* Unconditional breakpoints +* Watch window +* Call stack +* Stepping + + For more information on debugging with VS Code, see this introduction to [debugging in VS Code](/docs/editor/debugging.md). + +## Known Limitations + +### Symbols and Code Navigation + +All platforms: + +* Because the extension doesn't parse function bodies, Peek Definition and Go to Definition don't work for symbols defined inside the body of a function. + +### Debugging + +Windows: + +* GDB on Cygwin and MinGW cannot break a running process. To set a breakpoint when the application is running (not stopped under the debugger), or to pause the application being debugged, press `kbstyle(Ctrl-C)` in the application's terminal. +* GDB on Cygwin cannot open core dumps. + +Linux: + +* GDB needs elevated permissions to attach to a process. When using *attach to process*, you need to provide your password before the debugging session can begin. + +macOS: + +* LLDB: + * When debugging with LLDB, if the Terminal window is closed while in break mode, debugging does not stop. Debugging can be stopped by pressing the **Stop** button. + * When debugging is stopped the Terminal window is not closed. +* GDB: + * Additional manual install steps need to be completed to use GDB on macOS. See _Manual Installation of GDB for OS X_ in the [README](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools). + * When attaching to a process with GDB, the application being debugged cannot be interrupted. GDB will only bind breakpoints set while the application is not running (either before attaching to the application, or while the application is in a stopped state). This is due to [a bug in GDB](https://sourceware.org/bugzilla/show_bug.cgi?id=20035). + * Core dumps cannot be loaded when debugging with GDB because GDB [does not support the core dump format used in macOS](https://www.sourceware.org/ml/gdb/2014-01/msg00036.html). + * When attached to a process with GDB, break-all will end the process. + +## Next steps + +Read on to find out about: + +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Tasks](/docs/editor/tasks.md) - use tasks to build your project and more +* [Debugging](/docs/editor/debugging.md) - find out how to use the debugger with your project + +## Common questions + +### My project won't load + +VS Code doesn't currently support C++ project files, instead it considers a directory of your choosing to be the workspace of your project. Source code files inside that directory and its sub-directories are part of the workspace. + +### How do I build/run my project? + +VS Code supports tasks that you can configure to build your application, and natively understands the output of MSBuild, CSC, and XBuild. For more information, see the [Tasks](/docs/editor/tasks.md) documentation. + +If you have any other questions or run into any issues, please file an issue on [GitHub](https://github.com/Microsoft/vscode-cpptools/issues). diff --git a/docs/languages/csharp.md b/docs/languages/csharp.md new file mode 100644 index 0000000000000000000000000000000000000000..51293b32787546aa662719c5f8b452d94888196f --- /dev/null +++ b/docs/languages/csharp.md @@ -0,0 +1,138 @@ +--- +Order: 15 +Area: languages +TOCTitle: C# +ContentId: 40C8AAC1-C00D-4E91-8877-737A598346B6 +PageTitle: C# programming with Visual Studio Code +DateApproved: 7/16/2018 +MetaDescription: Find out how to get the best out of Visual Studio Code and C#. +MetaSocialImage: images/csharp/languages_csharp.png +--- +# Working with C# + +The C# support in Visual Studio Code is optimized for cross-platform .NET Core development (see [working with .NET Core and VS Code](/docs/other/dotnet.md) for another relevant article). Our focus with VS Code is to be a great editor for cross-platform C# development. + +![C# language within VS Code](images/csharp/c_sharp_hero.png) + +VS Code supports debugging of C# applications running on either .NET Core or Mono. + +For detailed instructions on: + +* .NET Core debugging - see the [Microsoft C# extension's GitHub page](https://github.com/OmniSharp/omnisharp-vscode/blob/master/debugger.md). +* Mono debugging - see the [Mono Debug extension's README](https://marketplace.visualstudio.com/items?itemName=ms-vscode.mono-debug). + +>**Note:** [VS Code has limited support for debugging applications running on the Desktop .NET Framework.](https://github.com/OmniSharp/omnisharp-vscode/wiki/Desktop-.NET-Framework) + +Due to this focus, many standard C# project types are not recognized by VS Code. An example of a non-supported project type is an ASP.NET MVC Application (though ASP.NET Core is supported). In these cases, if you want to have a lightweight tool to edit a file - VS Code has you covered. If you want the best possible experience for those projects and development on Windows in general, we recommend you use [Visual Studio Community](https://visualstudio.microsoft.com/vs/community). + +## Installing C# support + +C# language support is an optional [install from the Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp). You can install it from within VS Code by searching for 'C#' in the **Extensions** view (`kb(workbench.view.extensions)`) or if you already have a project with C# files, VS Code will prompt you to install the extension as soon as you open a C# file. + +[Video Tutorial on Getting Started with C# in VS Code with .NET Core](https://channel9.msdn.com/Blogs/dotnet/Get-started-VSCode-Csharp-NET-Core-Windows) + +In addition to the [Microsoft C# extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp), the community has produced other extensions. + +
+ +> Tip: The extensions shown above are dynamically queried. Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com). + +## Roslyn and OmniSharp + +Visual Studio Code uses the power of [Roslyn](https://github.com/dotnet/roslyn) and [OmniSharp](https://www.omnisharp.net) to offer an enhanced C# experience. We offer support for: + +* .NET Core projects +* MSBuild projects +* C# scripts (CSX) + +On startup the best matching projects are loaded automatically but you can also choose your projects manually. The status bar will show what projects have been loaded and also allows you to select a different set of projects. To do so, click on the status bar projects item and select *Change projects…*. In the image below a single project has been picked up: + +![Select Project](images/csharp/selectproject.png) + +The available options include: + +* Selecting a ```project.json``` file will open a .NET Core project and VS Code will load that project plus the referenced projects. +* Selecting a ```*.sln``` file opens a MSBuild-project. It will load the referenced ```*.csproj``` projects and sibling or descendant ```project.json``` files but no other project files that are referenced from the solution file. +* Selecting a ```folder``` will make VS Code scan for ```*.sln```, ```project.json``` and ```*.csx``` files (C# scripts) and VS Code will attempt to load them all. + +Once the project is loaded the enhanced experiences light up... + +## Editing Evolved + +There is a lot to discover with C# and the editor, such as format on type, IntelliSense, the rename-refactoring, etc. + +![Right Click Menu](images/csharp/editingevolved.png) + +For a full description of our editing features, go to the [Basic Editing](/docs/editor/codebasics.md) and [Code Navigation](/docs/editor/editingevolved.md) documentation. + +Here are a few highlights... + +## IntelliSense + +IntelliSense just works: hit `kb(editor.action.triggerSuggest)` at any time to get context specific suggestions. + +![IntelliSense](images/csharp/intellisense.png) + +## Snippets for C# + +We have several built-in snippets included in VS Code that will come up as you type or you can press `kb(editor.action.triggerSuggest)` (Trigger Suggest) and we will give you a context specific list of suggestions. + +![Snippets](images/csharp/snippet.png) + +>**Tip:** You can add in your own User Defined Snippets for C#. Take a look at [User Defined Snippets](/docs/editor/userdefinedsnippets.md) to find out how. + +## Search for Symbols + +There are also features outside the editor. One is the ability to search for symbols from wherever you are. Hit `kb(workbench.action.showAllSymbols)`, start typing, and see a list of matching C# symbols. Select one and you’ll be taken straight to its code location. + +![Symbols](images/csharp/symbols.png) + +## CodeLens + +Another cool feature is the ability to see the number of references to a method directly above the method. Click on the reference info to see the references in the Peek view. This reference information updates as you type. + +>**Note:** Methods defined in `object`, such as `equals` and `hashCode` do not get reference information due to performance reasons. + +![CodeLens](images/csharp/codelens.png) + +>**Tip:** You can turn off references information displayed in CodeLens with the `editor.codeLens` [setting](/docs/getstarted/settings.md). + +## Find References/Peek Definition + +You can click on the references of an object to find the locations of its use in place without losing context. This same experience works in reverse where you can Peek the definition of an object and see it inline without leaving your location. + +![Peek](images/csharp/peek.png) + +## Quick Fixes / Suggestions + +There are some basic quick fixes supported in VS Code. You will see a lightbulb and clicking on it, or pressing `kb(editor.action.quickFix)` provides you with a simple list of fixes/suggestions. + +![Quick fix](images/csharp/lightbulb.png) + +## Next steps + +Read on to find out about: + +* [.NET Core Development](/docs/other/dotnet.md) - get up and running with cross-platform .NET +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Tasks](/docs/editor/tasks.md) - use tasks to build your project and more +* [Debugging](/docs/editor/debugging.md) - find out how to use the debugger with your project + +## Common questions + +### My Project won't load + +VS Code only supports a limited set of project types (primarily .NET Core). For full .NET project support, we suggest you use [Visual Studio Community](https://visualstudio.microsoft.com/vs/community). + +### IntelliSense is not working + +This is typically as a result of the current project type not being supported. You can see an indication in the OmniSharp flame in the bottom left hand side of the status bar. + +### How do I build/run my project? + +VS Code supports tasks for build and natively understand the output of MSBuild, CSC, XBuild. Find out more in the [Tasks](/docs/editor/tasks.md) documentation. + +### I'm missing required assets to build and debug C# in VS Code. My debugger says "No Configuration" + +The Visual Studio Code C# extension can generate the assets you need to build and debug. If you missed the prompt when you first opened a new C# project, you can still perform this operation through the Command Palette (**View > Command Palette**) by typing '.NET', and running **.NET: Generate Assets for Build and Debug**. This command will generate the necessary `launch.json` and `tasks.json` configuration files (under the `.vscode` folder). diff --git a/docs/languages/css.md b/docs/languages/css.md new file mode 100644 index 0000000000000000000000000000000000000000..ef98e1fa94b53be2d8ecea80dca61fec980b42c4 --- /dev/null +++ b/docs/languages/css.md @@ -0,0 +1,333 @@ +--- +Order: 5 +Area: languages +TOCTitle: CSS, SCSS and Less +ContentId: 039882CB-B5C4-46BD-A8D5-DB24A5E82706 +PageTitle: CSS, SCSS, and Less support in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Find out how Visual Studio Code can support your CSS, SCSS and Less development. +--- +# CSS, SCSS and Less + +Visual Studio Code has built-in support for editing style sheets in CSS `.css`, SCSS `.scss` and Less `.less`. In addition, you can install an extension for greater functionality. + +
+ +> **Tip:** Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com). + +## IntelliSense + +VS Code has support for selectors, properties and values. Use `kb(editor.action.triggerSuggest)` to get a list of context specific options. + +![IntelliSense in CSS](images/css/intellisense.png) + +Proposals contain extensive documentation, including a list of browsers that support the property. To see the full description text of the selected entry, use `kb(toggleSuggestionDetails)`. + +## Syntax coloring & color preview + +As you type, there is syntax highlighting as well as in context preview of colors. + +![Syntax and color](images/css/color.png) + +Clicking on a color preview will launch the integrated color picker which supports configuration of hue, saturation and opacity. + +![Color picker in CSS](images/css/css-color-picker.png) + +> **Tip:** You can trigger between different color modes by clicking on the color string at the top of the picker. + +You can hide VS Code's color previews by setting the following [setting](/docs/getstarted/settings.md): + +```json +"editor.colorDecorators": false +``` + +To just disable it for css, Less and SCSS, use + +```json +"[css]": { + "editor.colorDecorators": false +} + +``` + +## Folding + +You can fold regions of source code using the folding icons on the gutter between line numbers and line start. Folding ranges are available for all declarations (e.g. rule declarations) and for multiline comments in the source code. + +Additionally you can use the following region markers to define a folding range: +`/*#region*/` and `/*#endregion*/` in CSS/SCSS/Less or `// #region` and `// #endregion` In SCSS/Less. + +If you prefer to switch to indentation based folding for CSS, Less and SCSS, use: + +```json +"[css]": { + "editor.foldingStrategy": "indentation" +}, +``` + + +## Emmet snippets + +[Emmet abbreviation support](/docs/editor/emmet.md) is built into VS Code, suggestions are listed along with other suggestions and snippets in the editor auto-completion list. + +>**Tip:** See the CSS section of the [Emmet cheat sheet](https://docs.emmet.io/cheat-sheet) for valid abbreviations. + +VS Code also supports [User Defined Snippets](/docs/editor/userdefinedsnippets.md). + +## Syntax Verification & Linting + +There is support for CSS version <= 2.1, Sass version <= 3.2 and Less version <= 2.3. + +>**Note:** You can disable VS Code's default CSS, Sass or Less validation by setting the corresponding `.validate` User or Workspace [setting](/docs/getstarted/settings.md) to false. +>```json +>"css.validate": false +>``` + +## Go to Symbol in file + +You can quickly navigate to the relevant CSS symbol from any file by pressing `kb(workbench.action.gotoSymbol)`. + +## Hovers + +Hovering over a selector or property will provide an HTML snippet that is matched by the CSS rule. + +![Hover in CSS](images/css/hover.png) + +## Go to Declaration and Find References + +This is supported for Sass and Less variables in the same file. [CSS variables](https://developer.mozilla.org/docs/Web/CSS/Using_CSS_variables) per the [draft standards proposal](https://drafts.csswg.org/css-variables/) are also supported. + +There is jump to definition for `@import` and `url()` links in CSS, SCSS and Less. + +## Transpiling Sass and Less into CSS + +VS Code can integrate with Sass and Less transpilers through our integrated [task runner](/docs/editor/tasks.md). We can use this to transpile `.scss` or `.less` files into `.css` files. Let's walk through transpiling a simple Sass/Less file. + +### Step 1: Install a Sass or Less transpiler + +For this walkthrough, let's use either the [node-sass](https://www.npmjs.com/package/node-sass) or [less](https://www.npmjs.com/package/less) Node.js module. + +>**Note:** If you don't have [Node.js](https://nodejs.org) and the [npm](https://www.npmjs.com/) package manager already installed, you'll need to do so for this walkthrough. [Install Node.js for your platform](https://nodejs.org/en/download/). The Node Package Manager (npm) is included in the Node.js distribution. You'll need to open a new terminal (command prompt) for `npm` to be on your PATH. + +```bash +npm install -g node-sass less +``` + +### Step 2: Create a simple Sass or Less file + +Open VS Code on an empty folder and create a `styles.scss` or `styles.less` file. Place the following code in that file: + +```scss +$padding: 6px; + +nav { + ul { + margin: 0; + padding: $padding; + list-style: none; + } + + li { display: inline-block; } + + a { + display: block; + padding: $padding 12px; + text-decoration: none; + } +} +``` + +For the Less version of the above file, just change `$padding` to `@padding`. + +>**Note:** This is a very simple example, which is why the source code is almost identical between both file types. In more advanced scenarios, the syntaxes and constructs will be much different. + +### Step 3: Create tasks.json + +The next step is to set up the task configuration. To do this, run **Terminal** > **Configure Tasks** and click **Create tasks.json file from templates**. In the selection dialog that shows up, select **Others**. + +This will create a sample `tasks.json` file in the workspace `.vscode` folder. The initial version of file has an example to run an arbitrary command. We will modify that configuration for transpiling Sass/Less instead: + +```json +// Sass configuration +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "Sass Compile", + "type": "shell", + "command": "node-sass styles.scss styles.css", + "group": "build" + } + ] +} +``` + +```json +// Less configuration +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "Less Compile", + "type": "shell", + "command": "lessc styles.less styles.css", + "group": "build" + } + ] +} +``` + +### Step 4: Run the Build Task + +As this is the only command in the file, you can execute it by pressing `kb(workbench.action.tasks.build)` (**Run Build Task**). The sample Sass/Less file should not have any compile problems, so by running the task all that happens is a corresponding `styles.css` file is created. + +Since in more complex environments there can be more than one build task we prompt you to pick the task to execute after pressing `kb(workbench.action.tasks.build)` (**Run Build Task**). In addition, we allow you to scan the output for compile problems (errors and warnings). Depending on the compiler, select an appropriate entry in the list to scan the tool output for errors and warnings. If you don't want to scan the output, select **Never scan the build output** from the presented list. + +At this point, you should see an additional file show up in the file list `styles.css`. + +If you want to make the task the default build task to run execute **Configure Default Build Task** from the global **Terminal** menu and select the corresponding **Sass** or **Less** task from the presented list. + +>**Note:** If your build fails or you see an error message such as "An output directory must be specified when compiling a directory", be sure the filenames in your `tasks.json` match the filenames on disk. You can always test your build by running `node-sass styles.scss styles.css` from the command line. + +## Automating Sass/Less compilation + +Let's take things a little further and automate Sass/Less compilation with VS Code. We can do so with the same task runner integration as before, but with a few modifications. + +### Step 1: Install Gulp and some plug-ins + +We will use [Gulp](https://gulpjs.com/) to create a task that will automate Sass/Less compilation. We will also use the [gulp-sass](https://www.npmjs.com/package/gulp-sass) plug-in to make things a little easier. The Less plug-in is [gulp-less](https://www.npmjs.com/package/gulp-less). + +We need to install gulp both globally (`-g` switch) and locally: + +```bash +npm install -g gulp +npm install gulp gulp-sass gulp-less +``` + +> **Note:** `gulp-sass` and `gulp-less` are Gulp plug-ins for the `node-sass` and `lessc` modules we were using before. There are many other Gulp Sass and Less plug-ins you can use, as well as plug-ins for Grunt. + +You can test that your gulp installation was successful by typing `gulp -v`. You should see a version displayed for both the global (CLI) and local installations. + +### Step 2: Create a simple Gulp task + +Open VS Code on the same folder from before (contains `styles.scss`/`styles.less` and `tasks.json` under the `.vscode` folder), and create `gulpfile.js` at the root. + +Place the following code in the `gulpfile.js` file: + +```javascript +// Sass configuration +var gulp = require('gulp'); +var sass = require('gulp-sass'); + +gulp.task('sass', function(cb) { + gulp.src('*.scss') + .pipe(sass()) + .pipe(gulp.dest(function(f) { + return f.base; + })); + cb(); +}); + +gulp.task('default', gulp.series('sass', function(cb) { + gulp.watch('*.scss', gulp.series('sass')); + cb(); +})); +``` + +```javascript +// Less configuration +var gulp = require('gulp'); +var less = require('gulp-less'); + +gulp.task('less', function(cb) { + gulp.src('*.less') + .pipe(less()) + .pipe(gulp.dest(function(f) { + return f.base; + })); + cb(); +}); + +gulp.task('default', gulp.series('less', function(cb) { + gulp.watch('*.less', gulp.series('less')); + cb(); +})); +``` + +What is happening here? + +1. Our `default` gulp task first runs the `sass` or `less` task once when it starts up. +2. It then watches for changes to any SCSS/Less file at the root of our workspace, for example the current folder open in VS Code. +3. It takes the set of SCSS/Less files that have changed and runs them through our respective compiler, for example `gulp-sass`, `gulp-less`. +4. We now have a set of CSS files, each named respectively after their original SCSS/Less file. We then put these files in the same directory. + +### Step 3: Run the gulp default task + +To complete the tasks integration with VS Code, we will need to modify the task configuration from before to run the default Gulp task we just created. You can either delete the `tasks.json` file or empty it only keeping the `"version": "2.0.0"` property. Now execute **Run Task** from the global **Terminal** menu. Observe that you are presented with a picker listing the tasks defined in the gulp file. Select **gulp: default** to start the task. We allow you to scan the output for compile problems. Depending on the compiler, select an appropriate entry in the list to scan the tool output for errors and warnings. If you don't want to scan the output, select **Never scan the build output** from the presented list. At this point, if you create and/or modify Less or SASS files, you see the respective CSS files generated and/or changes reflected on save. You can also enable [Auto Save](/docs/editor/codebasics.md#saveauto-save) to make things even more streamlined. + +If you want to make the **gulp: default** task the default build task executed when pressing `kb(workbench.action.tasks.build)` run **Configure Default Build Task** from the global **Terminal** menu and select **gulp: default** from the presented list. + +### Step 4: Terminate the gulp default Task + +The **gulp: default** task runs in the background and watches for file changes to Sass/Less files. If you want to stop the task, you can use the **Terminate Task** from the global **Terminal** menu. + +## Customizing CSS, SCSS and Less Settings + +You can configure the following lint warnings as [User and Workspace Settings](/docs/getstarted/settings.md). + +The `validate` setting allows you turn off the built-in validation. You would do this if you rather use a different linter. + +Id|Description|Default +---|------------|---- +css.validate | Enables or disables all css validations | true +less.validate | Enables or disables all less validations | true +scss.validate | Enables or disables all scss validations | true + +To configure an option for CSS, use `css.lint.` as the prefix to the id; for SCSS and Less, use `scss.lint.` and `less.lint.`. + +Set a setting to `warning` or `error` if you want to enable lint checking, use `ignore` to disable it. Lint checks are performed as you type. + +Id|Description|Default +---|------------|---- +validate | Enables or disables all validations | true +compatibleVendorPrefixes | When using a property with a vendor-specific prefix (for example `-webkit-transition`), make sure to also include all other vendor-specific properties e.g. `-moz-transition`, `-ms-transition` and `-o-transition` | ignore +vendorPrefix | When using a property with a vendor-specific prefix for example `-webkit-transition`, make sure to also include the standard property if it exists e.g. `transition` | warning +duplicateProperties | Warn about duplicate properties in the same ruleset | ignore +emptyRules | Warn about empty rulesets | warning +importStatement | Warn about using an `import` statement as import statements are loaded sequentially which has a negative impact on web page performance | ignore +boxModel | Do not use `width` or `height` when using `padding` or `border` | ignore +universalSelector | Warn when using the universal selector `*` as it is known to be slow and should be avoided | ignore +zeroUnits | Warn when having zero with a unit e.g. `0em` as zero does not need a unit. | ignore +fontFaceProperties | Warn when using `@font-face` rule without defining a `src` and `font-family` property | warning +hexColorLength | Warn when using hex numbers that don't consist of three or six hex numbers | error +argumentsInColorFunction | Warn when an invalid number of parameters in color functions e.g. `rgb` | error +unknownProperties | Warn when using an unknown property | warning +ieHack | Warn when using an IE hack `*propertyName` or `_propertyName` | ignore +unknownVendorSpecificProperties | Warn when using an unknown vendor-specific property | ignore +propertyIgnoredDueToDisplay | Warn when using a property that is ignored due to the display. For example, with `display: inline`, the `width`, `height`, `margin-top`, `margin-bottom`, and `float` properties have no effect. | warning +important | Warn when using `!important` as it is an indication that the specificity of the entire CSS has gotten out of control and needs to be refactored. | ignore +float | Warn when using `float` as floats lead to fragile CSS that is easy to break if one aspect of the layout changes. | ignore +idSelector | Warn when using selectors for an id `#id` as selectors should not contain IDs because these rules are too tightly coupled with the HTML. | ignore + +## Next steps + +Read on to find out about: + +* [Configure Tasks](/docs/editor/tasks.md) - Dig into Tasks to help you transpile your SCSS and Less to CSS. +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [HTML](/docs/languages/html.md) - CSS is just the start, HTML is also very well supported in VS Code. + +## Common questions + +### Does VS Code provide a color picker? + +Yes, color picker has been added in version [1.15](https://code.visualstudio.com/updates/v1_15#_color-picker). + +### Is there support for the indentation based Sass syntax (.sass)? + +No, but there are several extensions in the Marketplace supporting the indented flavor of Sass, for example, the [sass-indented](https://marketplace.visualstudio.com/items?itemName=robinbentley.sass-indented) extension by Robin Bentley. diff --git a/docs/languages/go.md b/docs/languages/go.md new file mode 100644 index 0000000000000000000000000000000000000000..dbd9e9782a6f667832c1b4985743fc6b1eb5c1c8 --- /dev/null +++ b/docs/languages/go.md @@ -0,0 +1,117 @@ +--- +Order: 12 +Area: languages +TOCTitle: Go +ContentId: 6f06908a-6694-4fad-ac1e-fc6d9c5747ca +PageTitle: Go with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Learn about Visual Studio Code editor features (code completion, debugging, snippets, linting) for Go. +--- +# Go in Visual Studio Code + +Using the Go extension for Visual Studio Code, you get language features like IntelliSense, code navigation, symbol search, bracket matching, snippets and many more that will help you in [Golang](https://golang.org/) development. + +![go extension banner](images/go/go-extension.png) + +You can install the Go extension from the VS Code [Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go). + +## IntelliSense + +### Auto completions + +As you type in a Go file, you can see IntelliSense providing you with suggested completions. This even works for members in current, imported, and not yet imported packages. Just type any package name followed by `.`, and you will get suggestions for the corresponding package members. + +By setting `go.autocompleteUnimportedPackages` to `true` in your [settings](/docs/getstarted/settings.md), you can also get suggestion for packages that you could import. Select one of these suggestions and an import to the selected package will be added to your file. + +>**Tip**: Use `kb(editor.action.triggerSuggest)` to trigger the suggestions manually. + +### Hover Information + +Hovering on any variable, function, or struct will give you information on that item such as documentation, signature, etc. + +![Information on hover](images/go/hover.png) + +By default, the extension uses `godef` and `godoc` to get this information. You can choose to use `gogetdoc` instead by changing the setting `go.docsTool` in your User or Workspace Settings. + +### Signature help + +When you open the `(` while calling a function, a pop-up provides signature help for the function. As you keep typing the parameters, the hint (underline) moves to the next parameter. + +![Signature Help](images/go/signaturehelp.png) + +>**Tip**: Use `kb(editor.action.triggerParameterHints)` to manually trigger the signature help when the cursor is inside the `()` in the function call. + +The extension's signature help also uses `godef` and `godoc`. You can choose to use `gogetdoc` instead by changing the setting `go.docsTool` in your User or Workspace Settings. + +## Code navigation + +Code navigation features are available in the context menu in the editor. + +- **Go To Definition** `kb(editor.action.revealDefinition)` - Go to the source code of the type definition. +- **Peek Definition** `kb(editor.action.peekDefinition)` - Bring up a Peek window with the type definition. +- **Peek References** `kb(editor.action.referenceSearch.trigger)` - Show all references for the type. + +You can navigate via symbol search using the **Go to Symbol** commands from the **Command Palette** (`kb(workbench.action.showCommands)`). + +- Go to Symbol in File - `kb(workbench.action.gotoSymbol)` +- Go to Symbol in Workspace - `kb(workbench.action.showAllSymbols)` + +You can also navigate back and forth between a Go file and its test implementation using the **Go: Toggle Test File** command. + +## Build, Lint and Vet + +On save, the Go extension can run `go build`, `go vet` and your choice of linting tool (`golint` or `gometalinter`) on the package of the current file. You can control these features via the settings below: + +- `go.buildOnSave` +- `go.buildFlags` +- `go.vetOnSave` +- `go.vetFlags` +- `go.lintOnSave` +- `go.lintFlags` +- `go.lintTool` +- `go.testOnSave` + +The errors and warnings from running any/all of the above will be shown red/green squiggly lines in the editor. These also show up in the **Problems** panel (**View** > **Problems**). + +## Formatting + +You can format your Go file using `kb(editor.action.formatDocument)` or by running the **Format Document** command from the **Command Palette** or the context menu in the editor. + +By default, formatting is run when you save your Go file. You can disable this behavior by setting `go.formatOnSave` to `false`. + +You can choose among three formatting tools: `gofmt`, `goreturns` and `goimports` by changing the setting `go.formatTool`. + +## Test + +There are many test related commands that you can explore by typing "Go: test" in the **Command Palette**. + +![Test Commands](images/go/testcommands.png) + +The first three above can be used to generate test skeletons for the functions in the current package, file or at cursor using `gotests`. The last few can be used to run tests in the current package, file or at cursor using `go test`. There is also a command for getting test coverage. + +## Import packages + +Run the command **Go: Add Import** to get a list of packages that can be imported to your Go file. Choose one and it will get added in the import block of your Go file. + +## Rename Symbols + +You can rename symbols using `kb(editor.action.rename)` or by running the **Rename Symbol** command in the context menu in the editor. + +## Debugging + +The Go extension lets you debug Go code as well. You will need to install the [Delve](https://github.com/derekparker/delve) debugger manually as a prerequisite. Read [Debugging Go code using VS Code](https://github.com/Microsoft/vscode-go/wiki/Debugging-Go-code-using-VS-Code) for setup steps, information on remote debugging and a troubleshooting guide. + +## Next steps + +This has been a brief overview showing the Go extension features within VS Code. For more information, see the details provided in the Go extension [README](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go). + +To stay up to date on the latest features/bug fixes for the Go extension, see the [CHANGELOG](https://github.com/Microsoft/vscode-go/blob/master/CHANGELOG.md). + +If you have any issues or feature requests, feel free to log them in the Go extension [repo](https://github.com/Microsoft/vscode-go/issues). + +If you'd like to learn more about VS Code, try these topics: + +* [Basic Editing](/docs/editor/codebasics.md) - A quick introduction to the basics of the VS Code editor. +* [Install an Extension](/docs/editor/extension-gallery.md) - Learn about other extensions are available in the [Marketplace](https://marketplace.visualstudio.com/vscode). +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. + diff --git a/docs/languages/html.md b/docs/languages/html.md new file mode 100644 index 0000000000000000000000000000000000000000..684ad9107dd0db9f179ef5c8d4b5876df3b3cbb5 --- /dev/null +++ b/docs/languages/html.md @@ -0,0 +1,165 @@ +--- +Order: 4 +Area: languages +TOCTitle: HTML +ContentId: 43095EAF-4B93-407C-A6F9-6DB173D79088 +PageTitle: HTML Programming with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Get the best out of Visual Studio Code for HTML development +--- +# HTML in Visual Studio Code + +Visual Studio Code provides basic support for HTML programming out of the box. There is syntax highlighting, smart completions with IntelliSense, and customizable formatting. VS Code also includes great Emmet support. + +## IntelliSense + +As you type in HTML, we offer suggestions via HTML IntelliSense. In the image below, you can see a suggested HTML element closure `` as well as a context specific list of suggested elements. + +![HTML IntelliSense](images/html/htmlintellisense.png) + +We also offer up suggestions for elements, tags, some values (as defined in HTML5), Ionic and AngularJS tags. Document symbols are also available for HTML, allowing you to quickly navigate to DOM nodes by id and class name. + +You can also work with embedded CSS and JavaScript. However, note that script and style includes from other files are not followed, the language support only looks at the content of the HTML file. + +You can trigger suggestions at any time by pressing `kb(editor.action.triggerSuggest)`. + +You can also control which built-in code completion providers are active. Override these in your user or workspace [settings](/docs/getstarted/settings.md) if you prefer not to see the corresponding suggestions. + +```json +// Configures if the built-in HTML language suggests Angular V1 tags and properties. +"html.suggest.angular1": true, + +// Configures if the built-in HTML language suggests Ionic tags, properties and values. +"html.suggest.ionic": true, + +// Configures if the built-in HTML language suggests HTML5 tags, properties and values. +"html.suggest.html5": true +``` + +## Close tags + +Tag elements are automatically closed when `>` of the opening tag is typed. + +![HTML Close1](images/html/auto-close1.gif) + +The matching closing tag is inserted when `/` of the closing tag is entered. + +![HTML Close2](images/html/auto-close2.gif) + +You can turn off autoclosing tags with the following [setting](/docs/getstarted/settings.md): + +```json +"html.autoClosingTags": false +``` + +## Color picker + +The VS Code color picker UI is now available in HTML style sections. + +![color picker in HTML](images/html/color-picker-html.png) + +It supports configuration of hue, saturation and opacity for the color that is picked up from the editor. It also provides the ability to trigger between different color modes by clicking on the color string at the top of the picker. The picker appears on a hover when you are over a color definition. + +## Hover + +Move the mouse over HTML tags or embedded styles and JavaScript to get more information on the symbol under the cursor. + +![HTML Hover](images/html/htmlhover.png) + +## Validation + +The HTML language support performs validation on all embedded JavaScript and CSS. + +You can turn that validation off with the following settings: + +```json +// Configures if the built-in HTML language support validates embedded scripts. +"html.validate.scripts": true, + +// Configures if the built-in HTML language support validates embedded styles. +"html.validate.styles": true +``` + +## Folding + +You can fold regions of source code using the folding icons on the gutter between line numbers and line start. Folding ranges are available for all HTML elements for multiline comments in the source code. + +Additionally you can use the following region markers to define a folding range: +`` and `` + +If you prefer to switch to indentation based folding for HTML use: + +```json +"[html]": { + "editor.foldingStrategy": "indentation" +}, +``` + +## Formatting + +To improve the formatting of your HTML source code, press `kb(editor.action.formatSelection)` and the selected area will be reformatted. + +The HTML formatter is based on [js-beautify](https://www.npmjs.com/package/js-beautify). The formatting options offered by that library are surfaced in the VS Code [settings](/docs/getstarted/settings.md): + +* `html.format.wrapLineLength`: Maximum amount of characters per line. +* `html.format.unformatted`: List of tags that shouldn't be reformatted. +* `html.format.contentUnformatted`: List of tags, comma separated, where the content shouldn't be reformatted. +* `html.format.extraLiners`: List of tags that should have an extra newline before them. +* `html.format.preserveNewLines`: Whether existing line breaks before elements should be preserved. +* `html.format.maxPreserveNewLines`: Maximum number of line breaks to be preserved in one chunk. +* `html.format.endWithNewline`: End with a newline. +* `html.format.indentInnerHtml`: Indent `` and `` sections. +* `html.format.wrapAttributes`: Wrapping strategy for attributes: + * `auto`: Wrap when the line length is exceeded + * `force`: Wrap all attributes, except first + * `force-aligned`: Wrap all attributes, except first, and align attributes + * `force-expand-multiline`: Wrap all attributes + +>**Tip:** The formatter doesn't format the tags listed in the `html.format.unformatted` and `html.format.contentUnformatted` settings. Embedded JavaScript is formatted unless 'script' tags are excluded. + +The Marketplace has several alternative formatters to choose from. If you want to use a different formatter, define +`"html.format.enable": false` in your settings to turn off the built-in formatter. + +## Emmet snippets + +VS Code supports [Emmet snippet](https://emmet.io/) expansion. Emmet abbreviations are listed along with other suggestions and snippets in the editor auto-completion list. + +![Emmet HTML support built-in](images/html/emmetsnippet.gif) + +>**Tip:** See the HTML section of the [Emmet cheat sheet](https://docs.emmet.io/cheat-sheet) for valid abbreviations. + +If you'd like to use HTML Emmet abbreviations with other languages, you can associate one of the Emmet modes (such as `css`, `html`) with other languages with the `emmet.includeLanguages` [setting](/docs/getstarted/settings.md). The setting takes a [language id](/docs/languages/overview.md#language-id) and associates it with the language id of an Emmet supported mode. + +For example, to use Emmet HTML abbreviations inside JavaScript: + +```json +{ + "emmet.includeLanguages": { + "javascript": "html" + } +} +``` + +We also support [User Defined Snippets](/docs/editor/userdefinedsnippets.md). + +## HTML extensions + +Install an extension to add more functionality. Go to the **Extensions** view (`kb(workbench.view.extensions)`) and type 'html' to see a list of relevant extensions to help with creating and editing HTML. + +
+ +> Tip: Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com). + +## Next steps + +Read on to find out about: + +* [CSS, SCSS, and Less](/docs/languages/css.md) - VS Code has first class support for CSS including Less and SCSS. +* [Emmet](/docs/editor/emmet.md) - Learn about VS Code's powerful built-in Emmet support. +* [Emmet official documentation](https://docs.emmet.io/) - Emmet, the essential toolkit for web-developers. + +## Common questions + +### Does VS Code have HTML preview? + +No, VS Code doesn't have built-in support for HTML preview but there are extensions available in the VS Code [Marketplace](https://marketplace.visualstudio.com/vscode). Open the **Extensions** view (`kb(workbench.view.extensions)`) and search on 'live preview' or 'html preview' to see a list of available HTML preview extensions. diff --git a/docs/languages/identifiers.md b/docs/languages/identifiers.md new file mode 100644 index 0000000000000000000000000000000000000000..3a56ba1616e9f945001c0d449728ed8535d93618 --- /dev/null +++ b/docs/languages/identifiers.md @@ -0,0 +1,114 @@ +--- +Area: languages +TOCTitle: Language Identifiers +ContentId: 3f773ade-7e71-4fb9-9bb9-d9e0b20fa799 +PageTitle: Visual Studio Code language identifiers +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code language mode identifiers +--- +# Language Identifiers + +In Visual Studio Code, each [language mode](/docs/languages/overview.md#changing-the-language-for-the-selected-file) has a unique specific language identifier. That identifier is rarely seen by the user except in the settings, for example, when associating file extensions to a language: + +```json + "files.associations": { + "*.myphp": "php" + } +``` + +Note that casing matters for exact identifier matching ('Markdown' != 'markdown') + +The language identifier becomes essential for VS Code extension developers when adding new language capabilities or when replacing a language support. + +Every language defines its *id* through the `languages` configuration point: + +```json + "languages": [{ + "id": "java", + "extensions": [ ".java", ".jav" ], + "aliases": [ "Java", "java" ] + }] +``` + +Language supports are added using the language identifier: + +```json + "grammars": [{ + "language": "groovy", + "scopeName": "source.groovy", + "path": "./syntaxes/Groovy.tmLanguage.json" + }], + "snippets": [{ + "language": "groovy", + "path": "./snippets/groovy.json" + }] +``` + +```typescript +languages.registerCompletionItemProvider('php', new PHPCompletionItemProvider(), '.', '$') +``` + +## New identifier guidelines + +When defining a new language identifier, use the following guidelines: + +- Use the lowercased programming language name. +- Search for other extensions in the Marketplace to find out if a language identifier has already been used. + +## Known language identifiers + +The following table lists known language identifiers: + +Language | Identifier +-------- | ---------- +ABAP | `abap` +Windows Bat | `bat` +BibTeX | `bibtex` +Clojure | `clojure` +Coffeescript | `coffeescript` +C | `c` +C++ | `cpp` +C# | `csharp` +CSS | `css` +Diff | `diff` +Dockerfile | `dockerfile` +F# | `fsharp` +Git | `git-commit` and `git-rebase` +Go | `go` +Groovy | `groovy` +Handlebars | `handlebars` +HTML | `html` +Ini | `ini` +Java | `java` +JavaScript | `javascript` +JavaScript React | `javascriptreact` +JSON | `json` +JSON with Comments | `jsonc` +LaTeX | `latex` +Less | `less` +Lua | `lua` +Makefile | `makefile` +Markdown | `markdown` +Objective-C | `objective-c` +Objective-C++ | `objective-cpp` +Perl | `perl` and `perl6` +PHP | `php` +Powershell | `powershell` +Pug | `jade` +Python | `python` +R | `r` +Razor (cshtml) | `razor` +Ruby | `ruby` +Rust | `rust` +SCSS | `scss` (syntax using curly brackets), `sass` (indented syntax) +ShaderLab | `shaderlab` +Shell Script (Bash) | `shellscript` +SQL | `sql` +Swift | `swift` +TypeScript | `typescript` +TypeScript React | `typescriptreact` +TeX | `tex` +Visual Basic | `vb` +XML | `xml` +XSL | `xsl` +YAML | `yaml` diff --git a/docs/languages/images/Markdown/double-click-preview-switch.gif b/docs/languages/images/Markdown/double-click-preview-switch.gif new file mode 100644 index 0000000000000000000000000000000000000000..f0be7cd15215f31a5210ceb51118ece7187bcd94 --- /dev/null +++ b/docs/languages/images/Markdown/double-click-preview-switch.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3c86088acd55ee8a08ee8517a085ad7ef7b3d9163721b225f1015e79157e2ea9 +size 593482 diff --git a/docs/languages/images/Markdown/locked-preview-title.png b/docs/languages/images/Markdown/locked-preview-title.png new file mode 100644 index 0000000000000000000000000000000000000000..4f800bd5b8b43101b0a1b3fc61444011a1e6a38a Binary files /dev/null and b/docs/languages/images/Markdown/locked-preview-title.png differ diff --git a/docs/languages/images/Markdown/markdown-outline-view.png b/docs/languages/images/Markdown/markdown-outline-view.png new file mode 100644 index 0000000000000000000000000000000000000000..ba1ce1ea4f4dca62a94e9bae36ce9df97cf99435 Binary files /dev/null and b/docs/languages/images/Markdown/markdown-outline-view.png differ diff --git a/docs/languages/images/Markdown/md-dynamic-preview.gif b/docs/languages/images/Markdown/md-dynamic-preview.gif new file mode 100644 index 0000000000000000000000000000000000000000..0a19906f64c6140152ce95bef24b5651773f1a3a --- /dev/null +++ b/docs/languages/images/Markdown/md-dynamic-preview.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:641e8eaee50f74adf27424811780b8761f923f5f2ee3aa2aac0b92113fe7ad6c +size 1837109 diff --git a/docs/languages/images/Markdown/preview-scroll-sync.gif b/docs/languages/images/Markdown/preview-scroll-sync.gif new file mode 100644 index 0000000000000000000000000000000000000000..72512a5319dcd34af2c416ec244c5de9ffde9396 --- /dev/null +++ b/docs/languages/images/Markdown/preview-scroll-sync.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9ea5a268122346e82ae221431fc53bcd8900cb09947e283a746c130bf9dc02f3 +size 3769713 diff --git a/docs/languages/images/Markdown/preview-selection-marker.png b/docs/languages/images/Markdown/preview-selection-marker.png new file mode 100644 index 0000000000000000000000000000000000000000..fe32b325caba0716c06aba8679668f194c528f83 Binary files /dev/null and b/docs/languages/images/Markdown/preview-selection-marker.png differ diff --git a/docs/languages/images/Markdown/preview.png b/docs/languages/images/Markdown/preview.png new file mode 100644 index 0000000000000000000000000000000000000000..962d91f078838a12c2e859934abacd41873f8a56 Binary files /dev/null and b/docs/languages/images/Markdown/preview.png differ diff --git a/docs/languages/images/Markdown/security-alert.png b/docs/languages/images/Markdown/security-alert.png new file mode 100644 index 0000000000000000000000000000000000000000..8658d9d753d10ab5f54dadae9cec6237d00b3cf5 --- /dev/null +++ b/docs/languages/images/Markdown/security-alert.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f88697aa3938ce8c13dbc5bef93c6f9708a0c186cd7cb1d2e20375aa51022b2c +size 897639 diff --git a/docs/languages/images/Markdown/security-selector.png b/docs/languages/images/Markdown/security-selector.png new file mode 100644 index 0000000000000000000000000000000000000000..e1641d119b0b87f1cdc19057c08221c72d51da77 Binary files /dev/null and b/docs/languages/images/Markdown/security-selector.png differ diff --git a/docs/languages/images/Markdown/taskwatching.png b/docs/languages/images/Markdown/taskwatching.png new file mode 100644 index 0000000000000000000000000000000000000000..b79b5ad92eb5a11f3a851a7e487fb5385e6f03ce Binary files /dev/null and b/docs/languages/images/Markdown/taskwatching.png differ diff --git a/docs/languages/images/cpp/condbreak.png b/docs/languages/images/cpp/condbreak.png new file mode 100644 index 0000000000000000000000000000000000000000..79655849176519153c41aaa3ebdbcbcd3d303faa Binary files /dev/null and b/docs/languages/images/cpp/condbreak.png differ diff --git a/docs/languages/images/cpp/cpp-extension.png b/docs/languages/images/cpp/cpp-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..de70fc7e45cb1bddf14bdd1dc04ae0b9125c8072 Binary files /dev/null and b/docs/languages/images/cpp/cpp-extension.png differ diff --git a/docs/languages/images/cpp/cpp-hero.png b/docs/languages/images/cpp/cpp-hero.png new file mode 100644 index 0000000000000000000000000000000000000000..4b78c8095eec16282bc40b433482cd327aad2603 Binary files /dev/null and b/docs/languages/images/cpp/cpp-hero.png differ diff --git a/docs/languages/images/cpp/cpp-lightbulb.png b/docs/languages/images/cpp/cpp-lightbulb.png new file mode 100644 index 0000000000000000000000000000000000000000..e82eb461db17f58f13121945b86ee66f8831a807 Binary files /dev/null and b/docs/languages/images/cpp/cpp-lightbulb.png differ diff --git a/docs/languages/images/cpp/filesearch.png b/docs/languages/images/cpp/filesearch.png new file mode 100644 index 0000000000000000000000000000000000000000..12c5ffdb29f001ba6858b2f61fdc109e2ad2fe98 Binary files /dev/null and b/docs/languages/images/cpp/filesearch.png differ diff --git a/docs/languages/images/cpp/includepath.gif b/docs/languages/images/cpp/includepath.gif new file mode 100644 index 0000000000000000000000000000000000000000..dc55b31a9d4091e28eac12d90565eb5570b5a5c8 --- /dev/null +++ b/docs/languages/images/cpp/includepath.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:72bf5946a734ee9bf145686e5b3930a53e2d18aabf4514d56e17bcc4b3aab006 +size 1019305 diff --git a/docs/languages/images/cpp/languages_cpp.png b/docs/languages/images/cpp/languages_cpp.png new file mode 100644 index 0000000000000000000000000000000000000000..7d2df7e6c22281e0466ddcdb628bc80880c6a558 --- /dev/null +++ b/docs/languages/images/cpp/languages_cpp.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:97d5a9e8ffd4e886086cc21f5772db80ee2619bcd88bfafc8352917aa24cbed2 +size 159605 diff --git a/docs/languages/images/cpp/launchjson.png b/docs/languages/images/cpp/launchjson.png new file mode 100644 index 0000000000000000000000000000000000000000..c61e4ec10fb51ad1fbd845d28d9dc394189075c7 Binary files /dev/null and b/docs/languages/images/cpp/launchjson.png differ diff --git a/docs/languages/images/cpp/parsing.png b/docs/languages/images/cpp/parsing.png new file mode 100644 index 0000000000000000000000000000000000000000..9e0bce32103e6989ab6b9e8c032bb17acf76236c Binary files /dev/null and b/docs/languages/images/cpp/parsing.png differ diff --git a/docs/languages/images/cpp/peekdefn.png b/docs/languages/images/cpp/peekdefn.png new file mode 100644 index 0000000000000000000000000000000000000000..f0ee19e50964a96a47ba1360a8d236bdce2e753b Binary files /dev/null and b/docs/languages/images/cpp/peekdefn.png differ diff --git a/docs/languages/images/cpp/threads.png b/docs/languages/images/cpp/threads.png new file mode 100644 index 0000000000000000000000000000000000000000..456ae093c1b8b80b1b2fc0428bbea919acd5132d Binary files /dev/null and b/docs/languages/images/cpp/threads.png differ diff --git a/docs/languages/images/cpp/workspacesearch.png b/docs/languages/images/cpp/workspacesearch.png new file mode 100644 index 0000000000000000000000000000000000000000..e6439758df2563adae824172e6456bd112179053 Binary files /dev/null and b/docs/languages/images/cpp/workspacesearch.png differ diff --git a/docs/languages/images/csharp/c_sharp_hero.png b/docs/languages/images/csharp/c_sharp_hero.png new file mode 100644 index 0000000000000000000000000000000000000000..6bf3ac11e81e3e3f19dacb2ae1c50f6986a3621c Binary files /dev/null and b/docs/languages/images/csharp/c_sharp_hero.png differ diff --git a/docs/languages/images/csharp/codelens.png b/docs/languages/images/csharp/codelens.png new file mode 100644 index 0000000000000000000000000000000000000000..2909c8f802ab9d8db64e5118e8fd469a69bdecac Binary files /dev/null and b/docs/languages/images/csharp/codelens.png differ diff --git a/docs/languages/images/csharp/editingevolved.png b/docs/languages/images/csharp/editingevolved.png new file mode 100644 index 0000000000000000000000000000000000000000..b853ab09be56f781d15f3c77431d6bfbffc93ec0 Binary files /dev/null and b/docs/languages/images/csharp/editingevolved.png differ diff --git a/docs/languages/images/csharp/intellisense.png b/docs/languages/images/csharp/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..70abcec461f8950acf3acaf60afda06751ab94d0 Binary files /dev/null and b/docs/languages/images/csharp/intellisense.png differ diff --git a/docs/languages/images/csharp/languages_csharp.png b/docs/languages/images/csharp/languages_csharp.png new file mode 100644 index 0000000000000000000000000000000000000000..845e0e018bcb9b1e4556c2ccc6390645d8a8bf14 --- /dev/null +++ b/docs/languages/images/csharp/languages_csharp.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5051555d5c1af3204d51b2c6a1ae753697fa06b6d3a781167fd0044bc385d16a +size 124644 diff --git a/docs/languages/images/csharp/lightbulb.png b/docs/languages/images/csharp/lightbulb.png new file mode 100644 index 0000000000000000000000000000000000000000..d119e55e5dc77363058976278422b7c067979b4f Binary files /dev/null and b/docs/languages/images/csharp/lightbulb.png differ diff --git a/docs/languages/images/csharp/peek.png b/docs/languages/images/csharp/peek.png new file mode 100644 index 0000000000000000000000000000000000000000..c6a3cbb58378740ca30f6c2bde1dc515e808784b Binary files /dev/null and b/docs/languages/images/csharp/peek.png differ diff --git a/docs/languages/images/csharp/selectproject.png b/docs/languages/images/csharp/selectproject.png new file mode 100644 index 0000000000000000000000000000000000000000..156f674b94f08c7e44c5afb9659c2265288bd626 Binary files /dev/null and b/docs/languages/images/csharp/selectproject.png differ diff --git a/docs/languages/images/csharp/snippet.png b/docs/languages/images/csharp/snippet.png new file mode 100644 index 0000000000000000000000000000000000000000..3a7d4b983ce0e756c13b2b87f6476120110deafe Binary files /dev/null and b/docs/languages/images/csharp/snippet.png differ diff --git a/docs/languages/images/csharp/symbols.png b/docs/languages/images/csharp/symbols.png new file mode 100644 index 0000000000000000000000000000000000000000..2a0edd38857332b99234073cb63022fb3e0f3321 Binary files /dev/null and b/docs/languages/images/csharp/symbols.png differ diff --git a/docs/languages/images/css/color.png b/docs/languages/images/css/color.png new file mode 100644 index 0000000000000000000000000000000000000000..d712270ee4d112a83a944031de57fdd82f66a729 Binary files /dev/null and b/docs/languages/images/css/color.png differ diff --git a/docs/languages/images/css/css-color-picker.png b/docs/languages/images/css/css-color-picker.png new file mode 100644 index 0000000000000000000000000000000000000000..a4cca2b94d009cf0c65d94dbc48ee4c00303fdf2 Binary files /dev/null and b/docs/languages/images/css/css-color-picker.png differ diff --git a/docs/languages/images/css/hover.png b/docs/languages/images/css/hover.png new file mode 100644 index 0000000000000000000000000000000000000000..a2393e79f600d4228b26599d33605436c88fc272 Binary files /dev/null and b/docs/languages/images/css/hover.png differ diff --git a/docs/languages/images/css/intellisense.png b/docs/languages/images/css/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..8e7f732a80bb04441b75fb20b51ec6151f459a00 Binary files /dev/null and b/docs/languages/images/css/intellisense.png differ diff --git a/docs/languages/images/css/taskwatching.png b/docs/languages/images/css/taskwatching.png new file mode 100644 index 0000000000000000000000000000000000000000..b79b5ad92eb5a11f3a851a7e487fb5385e6f03ce Binary files /dev/null and b/docs/languages/images/css/taskwatching.png differ diff --git a/docs/languages/images/go/go-extension.png b/docs/languages/images/go/go-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..84b15cfd6c8a4481cf417e36c641e374e44fe1e5 Binary files /dev/null and b/docs/languages/images/go/go-extension.png differ diff --git a/docs/languages/images/go/hover.png b/docs/languages/images/go/hover.png new file mode 100644 index 0000000000000000000000000000000000000000..850522a347fea302927d837453dbaaf088ce81a8 Binary files /dev/null and b/docs/languages/images/go/hover.png differ diff --git a/docs/languages/images/go/signaturehelp.png b/docs/languages/images/go/signaturehelp.png new file mode 100644 index 0000000000000000000000000000000000000000..1f9007ed5adc1b9b6663e68b65e37ef6fc065ab7 Binary files /dev/null and b/docs/languages/images/go/signaturehelp.png differ diff --git a/docs/languages/images/go/testcommands.png b/docs/languages/images/go/testcommands.png new file mode 100644 index 0000000000000000000000000000000000000000..3bf9f7932ac7dddac4696a8ee5e30abf7ee99dcd Binary files /dev/null and b/docs/languages/images/go/testcommands.png differ diff --git a/docs/languages/images/html/auto-close1.gif b/docs/languages/images/html/auto-close1.gif new file mode 100644 index 0000000000000000000000000000000000000000..ff4bd6a625ffe90dc79b5014a767dc088450cb8a --- /dev/null +++ b/docs/languages/images/html/auto-close1.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fdc932fcf089230387f4ea7ddaf5ebdf044293e49f3a40532fea00ca3ea76249 +size 101197 diff --git a/docs/languages/images/html/auto-close2.gif b/docs/languages/images/html/auto-close2.gif new file mode 100644 index 0000000000000000000000000000000000000000..52bd6d692b4cf7f960c0c0d01799c2f4270464f7 Binary files /dev/null and b/docs/languages/images/html/auto-close2.gif differ diff --git a/docs/languages/images/html/color-picker-html.png b/docs/languages/images/html/color-picker-html.png new file mode 100644 index 0000000000000000000000000000000000000000..f4ed9f2c300a1e62962666c13e303023504ce2fe Binary files /dev/null and b/docs/languages/images/html/color-picker-html.png differ diff --git a/docs/languages/images/html/emmetsnippet.gif b/docs/languages/images/html/emmetsnippet.gif new file mode 100644 index 0000000000000000000000000000000000000000..40a58546127ce4a094471923adc15dedca6c085c --- /dev/null +++ b/docs/languages/images/html/emmetsnippet.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:82f194f2b74764015768c47308feeaec03ef3484242357d2d870a2e38a20a117 +size 194330 diff --git a/docs/languages/images/html/htmlhover.png b/docs/languages/images/html/htmlhover.png new file mode 100644 index 0000000000000000000000000000000000000000..089081bd6df8b72beea5ee9855bc56336aea7ae3 Binary files /dev/null and b/docs/languages/images/html/htmlhover.png differ diff --git a/docs/languages/images/html/htmlintellisense.png b/docs/languages/images/html/htmlintellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..10c92eeac15257a701c4b060b2a87c82f8d2b813 Binary files /dev/null and b/docs/languages/images/html/htmlintellisense.png differ diff --git a/docs/languages/images/java/debug-features.png b/docs/languages/images/java/debug-features.png new file mode 100644 index 0000000000000000000000000000000000000000..253ff23d81d7cd0d25ba3579d06b570c1c4d392c Binary files /dev/null and b/docs/languages/images/java/debug-features.png differ diff --git a/docs/languages/images/java/extensions.png b/docs/languages/images/java/extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..4bc40ef6089258fdd7aec91d479eea7be963082d Binary files /dev/null and b/docs/languages/images/java/extensions.png differ diff --git a/docs/languages/images/java/intellisense.gif b/docs/languages/images/java/intellisense.gif new file mode 100644 index 0000000000000000000000000000000000000000..02bf308a810d83794693f9eb82cc535f40a2de02 --- /dev/null +++ b/docs/languages/images/java/intellisense.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:af93fd88776c91708691ce6f9e485f1c58bee2b2edd484a4fdc4038e76da9c2d +size 858841 diff --git a/docs/languages/images/java/java-debug.gif b/docs/languages/images/java/java-debug.gif new file mode 100644 index 0000000000000000000000000000000000000000..1a3cf5735a549718ee080f70ceb9dbc2c16078fb --- /dev/null +++ b/docs/languages/images/java/java-debug.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:81b0a4ae8a3b98ff8f30c125000cc446221791827c6bd5532237d346e8196062 +size 1694905 diff --git a/docs/languages/images/java/java-test-explorer.png b/docs/languages/images/java/java-test-explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..40da3bcfb5ac33112a0d91bbed6ffd60082b833a --- /dev/null +++ b/docs/languages/images/java/java-test-explorer.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:44c16a201c87a32cb7501d37e097f27c411528762e7f00aca72d2a2a3592ba36 +size 2680395 diff --git a/docs/languages/images/java/java-test.gif b/docs/languages/images/java/java-test.gif new file mode 100644 index 0000000000000000000000000000000000000000..1c9d6604150fb481eda2649e8b6c38209ffcd9b2 --- /dev/null +++ b/docs/languages/images/java/java-test.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5c7d9318b593f407d016c676acb2eb19d654aeee54e791c56c25b8de2a8463cf +size 1049909 diff --git a/docs/languages/images/java/package-viewer.gif b/docs/languages/images/java/package-viewer.gif new file mode 100644 index 0000000000000000000000000000000000000000..a04963d71597583046a8c9e9c26583f0599f873a --- /dev/null +++ b/docs/languages/images/java/package-viewer.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b11e6b7552153637304b47ff067d48519dc14398c4b6c9f58810910ea9da26e7 +size 424691 diff --git a/docs/languages/images/java/resolve-main.gif b/docs/languages/images/java/resolve-main.gif new file mode 100644 index 0000000000000000000000000000000000000000..2613328e0bfa778fecdd88b9bc9079cb50f58e1e --- /dev/null +++ b/docs/languages/images/java/resolve-main.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:05c025769a707d8443778a5c3cce4663cdac6a349fc8c19d0cda4d7694fe6ad0 +size 1009315 diff --git a/docs/languages/images/java/testng.gif b/docs/languages/images/java/testng.gif new file mode 100644 index 0000000000000000000000000000000000000000..b26cac3c08c95058ca3c0154a58f3e93d2add2ac --- /dev/null +++ b/docs/languages/images/java/testng.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b1413122442dbac84e8cec4df1371984ff802e13dc5b5b43d26203c07615afbd +size 820975 diff --git a/docs/languages/images/java/tomcat.gif b/docs/languages/images/java/tomcat.gif new file mode 100644 index 0000000000000000000000000000000000000000..3d3b1f4a429c12680af7eb3d74c6d6fc37e523ea --- /dev/null +++ b/docs/languages/images/java/tomcat.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:56eadc72716005c6b321742d62b271c08704c356005e35738feca0b79a2d07ab +size 2131679 diff --git a/docs/languages/images/java/vscode-java.0.0.1.gif b/docs/languages/images/java/vscode-java.0.0.1.gif new file mode 100644 index 0000000000000000000000000000000000000000..9ef88def5515854fab415bfb5097e5421cea16ad --- /dev/null +++ b/docs/languages/images/java/vscode-java.0.0.1.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:55800c5e2d93fd3556edb53a37ea17382227dbbe5d53b2b63183985bccdcb788 +size 2044204 diff --git a/docs/languages/images/javascript/auto-import-after.png b/docs/languages/images/javascript/auto-import-after.png new file mode 100644 index 0000000000000000000000000000000000000000..d49bb7230aa87699c1b6123c669615ae46b7b7dc Binary files /dev/null and b/docs/languages/images/javascript/auto-import-after.png differ diff --git a/docs/languages/images/javascript/auto-import-before.png b/docs/languages/images/javascript/auto-import-before.png new file mode 100644 index 0000000000000000000000000000000000000000..9e3c3094fa22d880847057a3b0db80cb16e6b24b Binary files /dev/null and b/docs/languages/images/javascript/auto-import-before.png differ diff --git a/docs/languages/images/javascript/checkjs-example.gif b/docs/languages/images/javascript/checkjs-example.gif new file mode 100644 index 0000000000000000000000000000000000000000..754b0cb95e747fd1eb17fb810327a140d0db2a4d --- /dev/null +++ b/docs/languages/images/javascript/checkjs-example.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:99174e3201f938c8e94d7b17de3844b6a782b41b86ad4bcfea8ee066a039446f +size 2408672 diff --git a/docs/languages/images/javascript/code-suggestions-convert-async-placeholder.png b/docs/languages/images/javascript/code-suggestions-convert-async-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..f5ce2cb9b5f4e5518f281afd9ca1b35d48bd39d2 Binary files /dev/null and b/docs/languages/images/javascript/code-suggestions-convert-async-placeholder.png differ diff --git a/docs/languages/images/javascript/code-suggestions-convert-async.mp4 b/docs/languages/images/javascript/code-suggestions-convert-async.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..afd6bee6e25c7a08e3e0ea8cd0be140ef206553f Binary files /dev/null and b/docs/languages/images/javascript/code-suggestions-convert-async.mp4 differ diff --git a/docs/languages/images/javascript/hover.png b/docs/languages/images/javascript/hover.png new file mode 100644 index 0000000000000000000000000000000000000000..7fd9148a1509ffd7215b733cb2a86cba2e654cbd Binary files /dev/null and b/docs/languages/images/javascript/hover.png differ diff --git a/docs/languages/images/javascript/intellisense-placeholder.png b/docs/languages/images/javascript/intellisense-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..ca86cb43a99d9a1f65fc6f6822843c1c94f1fc39 --- /dev/null +++ b/docs/languages/images/javascript/intellisense-placeholder.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6e070b6a08970a2fc3acd19c10b70d514e99252bf332dd402cac751b59aa81f3 +size 136590 diff --git a/docs/languages/images/javascript/intellisense.mp4 b/docs/languages/images/javascript/intellisense.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..21f080172802dea4eb2702748703f368c0a670de --- /dev/null +++ b/docs/languages/images/javascript/intellisense.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:21e31ee10fc39287a1744b36f447a56aaf382eee1af589efd5f67f1fa67ac191 +size 287208 diff --git a/docs/languages/images/javascript/jsdoc-autofill-placeholder.png b/docs/languages/images/javascript/jsdoc-autofill-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..09556ffba692d1d202d87a60df13cc1a8c614c40 Binary files /dev/null and b/docs/languages/images/javascript/jsdoc-autofill-placeholder.png differ diff --git a/docs/languages/images/javascript/jsdoc-autofill.mp4 b/docs/languages/images/javascript/jsdoc-autofill.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..066f2d556b53b20f44c58fa4a3c017d27e31c255 Binary files /dev/null and b/docs/languages/images/javascript/jsdoc-autofill.mp4 differ diff --git a/docs/languages/images/javascript/jsx.png b/docs/languages/images/javascript/jsx.png new file mode 100644 index 0000000000000000000000000000000000000000..ae9e88ca6c01bee5f6cb921e27987d08acd00fd8 --- /dev/null +++ b/docs/languages/images/javascript/jsx.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:57ff0fd6a3f8043ce4a4a6bcf4b03cc54231aabb29f46b7cef0e2a87d8a659b8 +size 111191 diff --git a/docs/languages/images/javascript/organize-imports-placeholder.png b/docs/languages/images/javascript/organize-imports-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..4e7cd32693949ded30ef806a6e67d1878cfda76b Binary files /dev/null and b/docs/languages/images/javascript/organize-imports-placeholder.png differ diff --git a/docs/languages/images/javascript/organize-imports.mp4 b/docs/languages/images/javascript/organize-imports.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..7b8493a12b7c3b3b15e2005def4118875042416f --- /dev/null +++ b/docs/languages/images/javascript/organize-imports.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4f4a92e830574166a47f6910fe377fa446a4bfaf834be5282d45ce07070878e9 +size 281753 diff --git a/docs/languages/images/javascript/overview.png b/docs/languages/images/javascript/overview.png new file mode 100644 index 0000000000000000000000000000000000000000..20174a142c5b4c7b3501af6df7f56fc40ab83c1e --- /dev/null +++ b/docs/languages/images/javascript/overview.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:95afea43a716161eb5ea65b90b137c450ea335d4edcb9e0881a59346fdd3ce08 +size 499669 diff --git a/docs/languages/images/javascript/refactorings.png b/docs/languages/images/javascript/refactorings.png new file mode 100644 index 0000000000000000000000000000000000000000..26dd6a749288e1faab337920d958f34eafc26166 Binary files /dev/null and b/docs/languages/images/javascript/refactorings.png differ diff --git a/docs/languages/images/javascript/rename.png b/docs/languages/images/javascript/rename.png new file mode 100644 index 0000000000000000000000000000000000000000..1b4b8de43fbd56d7f9e87b35de3ab71767db8cbd Binary files /dev/null and b/docs/languages/images/javascript/rename.png differ diff --git a/docs/languages/images/javascript/signature-help.png b/docs/languages/images/javascript/signature-help.png new file mode 100644 index 0000000000000000000000000000000000000000..d46536cf03650ecc2cc27fe70a4815f88fe9aac8 Binary files /dev/null and b/docs/languages/images/javascript/signature-help.png differ diff --git a/docs/languages/images/javascript/snippets-placeholder.png b/docs/languages/images/javascript/snippets-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..a7d6734be4a0f68993a65576ca92622e524d3331 Binary files /dev/null and b/docs/languages/images/javascript/snippets-placeholder.png differ diff --git a/docs/languages/images/javascript/snippets.mp4 b/docs/languages/images/javascript/snippets.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..b92daa26c00c8573ff94a24c401e69e99faf753e Binary files /dev/null and b/docs/languages/images/javascript/snippets.mp4 differ diff --git a/docs/languages/images/javascript/tag-complete-placeholder.png b/docs/languages/images/javascript/tag-complete-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..7e4793f6ccfaeaaa6e707b4bd30820e2d6c090db Binary files /dev/null and b/docs/languages/images/javascript/tag-complete-placeholder.png differ diff --git a/docs/languages/images/javascript/tag-complete.mp4 b/docs/languages/images/javascript/tag-complete.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..bba7ee62fd4d203a799dc3b59cfa2eccb46500db --- /dev/null +++ b/docs/languages/images/javascript/tag-complete.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5de065c76cea4fab10ff7d340299b70bed418a011beea8217a078e7762fe6486 +size 146465 diff --git a/docs/languages/images/javascript/unreachable.png b/docs/languages/images/javascript/unreachable.png new file mode 100644 index 0000000000000000000000000000000000000000..64d07fc05cf94fb2a55d354a0f6449f4aa5945a1 Binary files /dev/null and b/docs/languages/images/javascript/unreachable.png differ diff --git a/docs/languages/images/javascript/update-imports-placeholder.png b/docs/languages/images/javascript/update-imports-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..ebc6d1b374dd03e61f1cf1b9d9b2e514000eaf46 --- /dev/null +++ b/docs/languages/images/javascript/update-imports-placeholder.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:11870aa8f214a1c7c69fb6cd48ad25de9ced60f8ca79dc5776e0b00c5e8fbd2f +size 244637 diff --git a/docs/languages/images/javascript/update-imports.mp4 b/docs/languages/images/javascript/update-imports.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..649397d52de1b429257a7a65ef371ecdc54e2742 --- /dev/null +++ b/docs/languages/images/javascript/update-imports.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7dd6703859d879050755e16bd5054a160200a0b1a69a3e32d3d091781b284834 +size 221820 diff --git a/docs/languages/images/json/gotosymbol.png b/docs/languages/images/json/gotosymbol.png new file mode 100644 index 0000000000000000000000000000000000000000..ae6359d3b7d7bd3782dd73baf774cc7e04309df0 Binary files /dev/null and b/docs/languages/images/json/gotosymbol.png differ diff --git a/docs/languages/images/json/hoverandtoggle.png b/docs/languages/images/json/hoverandtoggle.png new file mode 100644 index 0000000000000000000000000000000000000000..eb4e1c82ffe0252070335d65fe88bc82c21f6c0a Binary files /dev/null and b/docs/languages/images/json/hoverandtoggle.png differ diff --git a/docs/languages/images/json/intellisense.png b/docs/languages/images/json/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..1cc0439719e76c2b7815eb1d1a2c9fa9ad23f327 Binary files /dev/null and b/docs/languages/images/json/intellisense.png differ diff --git a/docs/languages/images/json/json_hero.png b/docs/languages/images/json/json_hero.png new file mode 100644 index 0000000000000000000000000000000000000000..703f7a197164c9de8e5c07bc8604dd9b3fb71871 Binary files /dev/null and b/docs/languages/images/json/json_hero.png differ diff --git a/docs/languages/images/overview/language-id-intellisense.png b/docs/languages/images/overview/language-id-intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..55d587cbe8cb4f8f76b119abe33d3b7bc056530c Binary files /dev/null and b/docs/languages/images/overview/language-id-intellisense.png differ diff --git a/docs/languages/images/overview/language-identifiers.png b/docs/languages/images/overview/language-identifiers.png new file mode 100644 index 0000000000000000000000000000000000000000..52f9b6a55b17d843dbca80c8f93f8625a51f6e4f Binary files /dev/null and b/docs/languages/images/overview/language-identifiers.png differ diff --git a/docs/languages/images/overview/languageselect.png b/docs/languages/images/overview/languageselect.png new file mode 100644 index 0000000000000000000000000000000000000000..8c44c25cb03875c4aaa241d477cf78c4234e54d0 Binary files /dev/null and b/docs/languages/images/overview/languageselect.png differ diff --git a/docs/languages/images/php/php-settings.png b/docs/languages/images/php/php-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..a3e620db6c9d969d3db442433fa96e6444c16ce6 Binary files /dev/null and b/docs/languages/images/php/php-settings.png differ diff --git a/docs/languages/images/php/php-snippets.png b/docs/languages/images/php/php-snippets.png new file mode 100644 index 0000000000000000000000000000000000000000..58030599908a72d585e72117e55f475641c230d2 Binary files /dev/null and b/docs/languages/images/php/php-snippets.png differ diff --git a/docs/languages/images/powershell/HSGavatar.png b/docs/languages/images/powershell/HSGavatar.png new file mode 100644 index 0000000000000000000000000000000000000000..e71569235b05347a5c8957ecd5832e7e45df8fb5 Binary files /dev/null and b/docs/languages/images/powershell/HSGavatar.png differ diff --git a/docs/languages/images/powershell/PowerShellExtension.png b/docs/languages/images/powershell/PowerShellExtension.png new file mode 100644 index 0000000000000000000000000000000000000000..95f8ccfe6fdd946959a4462ed8e3ff6e294bc943 Binary files /dev/null and b/docs/languages/images/powershell/PowerShellExtension.png differ diff --git a/docs/languages/images/powershell/codeGear.png b/docs/languages/images/powershell/codeGear.png new file mode 100644 index 0000000000000000000000000000000000000000..3fcee013a9d2cbc61d154683dba8e888395eaa67 Binary files /dev/null and b/docs/languages/images/powershell/codeGear.png differ diff --git a/docs/languages/images/powershell/codeLensFuncRef.gif b/docs/languages/images/powershell/codeLensFuncRef.gif new file mode 100644 index 0000000000000000000000000000000000000000..ce5bc26ba778469f10c337ca8b57668961e15ed0 --- /dev/null +++ b/docs/languages/images/powershell/codeLensFuncRef.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0b159ef55c430b8150531a62452f6c42db344ba8c67f3987beaee1818d1546ef +size 2730623 diff --git a/docs/languages/images/powershell/codeLensPesterDebug.gif b/docs/languages/images/powershell/codeLensPesterDebug.gif new file mode 100644 index 0000000000000000000000000000000000000000..c0ae70c67b1e78f8f1ac5c90a5c7715386d14c7d --- /dev/null +++ b/docs/languages/images/powershell/codeLensPesterDebug.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:207ebb1b17339734f12ee6c4aab4b7bccb3f9fbd53caa454dd460817d8656ed7 +size 1887463 diff --git a/docs/languages/images/powershell/codeLensPesterSymbol.gif b/docs/languages/images/powershell/codeLensPesterSymbol.gif new file mode 100644 index 0000000000000000000000000000000000000000..3e5fecb0458f13fd12b9a6c709427bf9e9449bcf --- /dev/null +++ b/docs/languages/images/powershell/codeLensPesterSymbol.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a75bf3dc2c84f52ded491dca4b437b74770b9a6da75a6ef432b3a1aa56b1ebb8 +size 2069934 diff --git a/docs/languages/images/powershell/cpPlasterCommand.png b/docs/languages/images/powershell/cpPlasterCommand.png new file mode 100644 index 0000000000000000000000000000000000000000..dffdf7db948647546e9e9076c82ac3ec452cb776 Binary files /dev/null and b/docs/languages/images/powershell/cpPlasterCommand.png differ diff --git a/docs/languages/images/powershell/extensionBrowser.png b/docs/languages/images/powershell/extensionBrowser.png new file mode 100644 index 0000000000000000000000000000000000000000..0b81ee86e7969949f1ccb11c084f122d33906435 Binary files /dev/null and b/docs/languages/images/powershell/extensionBrowser.png differ diff --git a/docs/languages/images/powershell/pesterCodeLens.png b/docs/languages/images/powershell/pesterCodeLens.png new file mode 100644 index 0000000000000000000000000000000000000000..4c4da91297af9a95f6efaaa84aa6aeb9dc26a0f5 Binary files /dev/null and b/docs/languages/images/powershell/pesterCodeLens.png differ diff --git a/docs/languages/images/powershell/pssaExtensionSetting.png b/docs/languages/images/powershell/pssaExtensionSetting.png new file mode 100644 index 0000000000000000000000000000000000000000..cf28a29fe876b1d578e9af3aaee834963a1d27b1 Binary files /dev/null and b/docs/languages/images/powershell/pssaExtensionSetting.png differ diff --git a/docs/languages/images/powershell/pwshChangeVersion.png b/docs/languages/images/powershell/pwshChangeVersion.png new file mode 100644 index 0000000000000000000000000000000000000000..aadff98498f701d3123c2c89b392d2f9c91b82b8 Binary files /dev/null and b/docs/languages/images/powershell/pwshChangeVersion.png differ diff --git a/docs/languages/images/powershell/pwshCodeSettings.png b/docs/languages/images/powershell/pwshCodeSettings.png new file mode 100644 index 0000000000000000000000000000000000000000..86153b9106e4ffdf535afb9c97a17eb7369f44c8 Binary files /dev/null and b/docs/languages/images/powershell/pwshCodeSettings.png differ diff --git a/docs/languages/images/powershell/pwshExamples.png b/docs/languages/images/powershell/pwshExamples.png new file mode 100644 index 0000000000000000000000000000000000000000..353c666e6f486c15d3d506f5b8f1d278a9a5d085 Binary files /dev/null and b/docs/languages/images/powershell/pwshExamples.png differ diff --git a/docs/languages/images/powershell/pwshExtensionIcon.png b/docs/languages/images/powershell/pwshExtensionIcon.png new file mode 100644 index 0000000000000000000000000000000000000000..fcd07ea0f8b368b29d329f5919c7642a68490e8c Binary files /dev/null and b/docs/languages/images/powershell/pwshExtensionIcon.png differ diff --git a/docs/languages/images/powershell/pwshSettings.png b/docs/languages/images/powershell/pwshSettings.png new file mode 100644 index 0000000000000000000000000000000000000000..7cef5f5312eb2ee719af1188020633f78d1e602a Binary files /dev/null and b/docs/languages/images/powershell/pwshSettings.png differ diff --git a/docs/languages/images/powershell/pwshVsixIcon.png b/docs/languages/images/powershell/pwshVsixIcon.png new file mode 100644 index 0000000000000000000000000000000000000000..10104ec30398a0dd9e2e1ef07160e7d3a22bfcd3 Binary files /dev/null and b/docs/languages/images/powershell/pwshVsixIcon.png differ diff --git a/docs/languages/images/powershell/vscodeSettingsGui.png b/docs/languages/images/powershell/vscodeSettingsGui.png new file mode 100644 index 0000000000000000000000000000000000000000..771004f7f9134a1f0e9f3ae2eb2ecc9ba1131c5f Binary files /dev/null and b/docs/languages/images/powershell/vscodeSettingsGui.png differ diff --git a/docs/languages/images/powershell/vscodeSettingsMenu.png b/docs/languages/images/powershell/vscodeSettingsMenu.png new file mode 100644 index 0000000000000000000000000000000000000000..b5a0c1f34565d933f64a1486ba00acc620f7f981 Binary files /dev/null and b/docs/languages/images/powershell/vscodeSettingsMenu.png differ diff --git a/docs/languages/images/python/feature_showcase.mp4 b/docs/languages/images/python/feature_showcase.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..1176ec137e10a30dc2f00a02691e7c06990887e8 --- /dev/null +++ b/docs/languages/images/python/feature_showcase.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:212369f0efa523948e75ba0f071529d0ea5ab3b789a0e367b7892c2ee44abdf7 +size 7393889 diff --git a/docs/languages/images/python/interpreters-list.png b/docs/languages/images/python/interpreters-list.png new file mode 100644 index 0000000000000000000000000000000000000000..5f1ce1f20d48a286d4ce37dbe24d4ffec0797842 Binary files /dev/null and b/docs/languages/images/python/interpreters-list.png differ diff --git a/docs/languages/images/python/jupyter.png b/docs/languages/images/python/jupyter.png new file mode 100644 index 0000000000000000000000000000000000000000..c94e6b47ac841d685c208dbdfea8fedf326e46e8 --- /dev/null +++ b/docs/languages/images/python/jupyter.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1572e2f196da6f0f5aad6123d462166baccb0e9c4f01c5d62e69a0dca2022ea4 +size 362782 diff --git a/docs/languages/images/python/no-interpreter-selected-statusbar.png b/docs/languages/images/python/no-interpreter-selected-statusbar.png new file mode 100644 index 0000000000000000000000000000000000000000..6a9c402ee74ea5f426ed0cc9f59e49997cb53b9a Binary files /dev/null and b/docs/languages/images/python/no-interpreter-selected-statusbar.png differ diff --git a/docs/languages/images/python/python-debugging-placeholder.png b/docs/languages/images/python/python-debugging-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..4e4e11e3de8f980feebf9c7bdc7ee824c43b3442 Binary files /dev/null and b/docs/languages/images/python/python-debugging-placeholder.png differ diff --git a/docs/languages/images/python/python-debugging.mp4 b/docs/languages/images/python/python-debugging.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..f165e80f53422011fe723caaa51d0a5dd5ea52c6 --- /dev/null +++ b/docs/languages/images/python/python-debugging.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f2f185baf41cee90416d864639d029d6896bb76617091b576dcbd869c6567bcf +size 720925 diff --git a/docs/languages/images/python/python-editing.gif b/docs/languages/images/python/python-editing.gif new file mode 100644 index 0000000000000000000000000000000000000000..446342f5b479399d4ec60dbeb65f97e7fea055b6 --- /dev/null +++ b/docs/languages/images/python/python-editing.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:54550025e838173e979e79c9a8c931bb00e38aa2f1357dba40870531ec27cf16 +size 595936 diff --git a/docs/languages/images/python/python-linting-placeholder.png b/docs/languages/images/python/python-linting-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..33d32d9aab8511f2c6a1014493b37f9eac2fd444 Binary files /dev/null and b/docs/languages/images/python/python-linting-placeholder.png differ diff --git a/docs/languages/images/python/python-linting.mp4 b/docs/languages/images/python/python-linting.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..307e30c8ca4f4319135a0a62b437172d66ccf1b0 --- /dev/null +++ b/docs/languages/images/python/python-linting.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8d01101e1a804a28931a2dce683691430274b546692bcd1c581b7e0f9676a59a +size 699074 diff --git a/docs/languages/images/python/python-snippets-placeholder.png b/docs/languages/images/python/python-snippets-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..77e4a73856c19b7e72a0f1b9a5c038f304377484 Binary files /dev/null and b/docs/languages/images/python/python-snippets-placeholder.png differ diff --git a/docs/languages/images/python/python-snippets.mp4 b/docs/languages/images/python/python-snippets.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..d7e53af8c2bd947d2984471640b5187c1cc70591 --- /dev/null +++ b/docs/languages/images/python/python-snippets.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:739d6734eb75516e44dd03c2c2422919091b45dfae6ad70b6cd12d30cc24de84 +size 252592 diff --git a/docs/languages/images/python/select-interpreters-command.png b/docs/languages/images/python/select-interpreters-command.png new file mode 100644 index 0000000000000000000000000000000000000000..dfc64aa3ce7237778c3cd649ff72e48cc9302400 Binary files /dev/null and b/docs/languages/images/python/select-interpreters-command.png differ diff --git a/docs/languages/images/python/selected-interpreter-status-bar.png b/docs/languages/images/python/selected-interpreter-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..5cf950344fc304690e2b188c29c8e9ff1cf65d38 Binary files /dev/null and b/docs/languages/images/python/selected-interpreter-status-bar.png differ diff --git a/docs/languages/images/tsql/execute.gif b/docs/languages/images/tsql/execute.gif new file mode 100644 index 0000000000000000000000000000000000000000..212b3955bf11a4fcbafd9e6c22b48dee27247212 --- /dev/null +++ b/docs/languages/images/tsql/execute.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fea89cbbef93d3d5cd964659be8f4d7e1acbd9668d5f649c19a47ffd35dfba25 +size 240949 diff --git a/docs/languages/images/tsql/install-mssql.png b/docs/languages/images/tsql/install-mssql.png new file mode 100644 index 0000000000000000000000000000000000000000..962bf62117691f7c5203efd5a26c3d64defa1524 Binary files /dev/null and b/docs/languages/images/tsql/install-mssql.png differ diff --git a/docs/languages/images/tsql/intellisense.gif b/docs/languages/images/tsql/intellisense.gif new file mode 100644 index 0000000000000000000000000000000000000000..6710f3c6ccca3ebb301e7673cb17a933b7a43b6f --- /dev/null +++ b/docs/languages/images/tsql/intellisense.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:28a11ab3bb207b4de8e5624f4df8e0e0b8d5b72b86036b34c5c4c52bcd1ad8c1 +size 377230 diff --git a/docs/languages/images/tsql/linting.gif b/docs/languages/images/tsql/linting.gif new file mode 100644 index 0000000000000000000000000000000000000000..890cd01203ecd1b5a698b97c7698b12e421d5289 --- /dev/null +++ b/docs/languages/images/tsql/linting.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e65c54ef99a759ea78247870376deed2ae9f149dedab69be4bf73dcde416d271 +size 308016 diff --git a/docs/languages/images/tsql/peekdefinition.gif b/docs/languages/images/tsql/peekdefinition.gif new file mode 100644 index 0000000000000000000000000000000000000000..eadc262116f253a94f62cd80d23db8088953650e --- /dev/null +++ b/docs/languages/images/tsql/peekdefinition.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8575f56269b36f2d18164bab48d532b82cbd1844d273c1a31fd7c270ec62e5cb +size 276176 diff --git a/docs/languages/images/tsql/save.gif b/docs/languages/images/tsql/save.gif new file mode 100644 index 0000000000000000000000000000000000000000..e0d9636387ea7c7d05b26e16eee7c9a6ad0ad29a --- /dev/null +++ b/docs/languages/images/tsql/save.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fb31a4c6273db6986fb629eb189ed72ffbfb0d4202fd2e320554148dd16f34ef +size 378652 diff --git a/docs/languages/images/tsql/snippets.gif b/docs/languages/images/tsql/snippets.gif new file mode 100644 index 0000000000000000000000000000000000000000..2d1432d9c6347776e64f24eceb6c882b42c66956 --- /dev/null +++ b/docs/languages/images/tsql/snippets.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c00208b43504c53ff4d9a465114209718a6791d8e33d295f367d2a74de0afdce +size 376793 diff --git a/docs/languages/images/typescript/Languages_typescript.png b/docs/languages/images/typescript/Languages_typescript.png new file mode 100644 index 0000000000000000000000000000000000000000..446a6ce745f493fdf0c414a80de9e5e395fcbe9e --- /dev/null +++ b/docs/languages/images/typescript/Languages_typescript.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:00ba04cdc1750dee88fa31fe193b5c2d44a648c8e62a1ef5a55535ff86a94ba3 +size 131481 diff --git a/docs/languages/images/typescript/auto-import-post.png b/docs/languages/images/typescript/auto-import-post.png new file mode 100644 index 0000000000000000000000000000000000000000..23687238f56f4c12aaac7b57f47e10c76bf261b6 Binary files /dev/null and b/docs/languages/images/typescript/auto-import-post.png differ diff --git a/docs/languages/images/typescript/auto-import-pre.png b/docs/languages/images/typescript/auto-import-pre.png new file mode 100644 index 0000000000000000000000000000000000000000..2e0e879848e662672a6193a1af0841408347fd2d Binary files /dev/null and b/docs/languages/images/typescript/auto-import-pre.png differ diff --git a/docs/languages/images/typescript/code-suggestions-convert-async-placeholder.png b/docs/languages/images/typescript/code-suggestions-convert-async-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..f5ce2cb9b5f4e5518f281afd9ca1b35d48bd39d2 Binary files /dev/null and b/docs/languages/images/typescript/code-suggestions-convert-async-placeholder.png differ diff --git a/docs/languages/images/typescript/code-suggestions-convert-async.mp4 b/docs/languages/images/typescript/code-suggestions-convert-async.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..afd6bee6e25c7a08e3e0ea8cd0be140ef206553f Binary files /dev/null and b/docs/languages/images/typescript/code-suggestions-convert-async.mp4 differ diff --git a/docs/languages/images/typescript/hover.png b/docs/languages/images/typescript/hover.png new file mode 100644 index 0000000000000000000000000000000000000000..f22257f810a779e7536e6b6d01fc33fa05beb93f Binary files /dev/null and b/docs/languages/images/typescript/hover.png differ diff --git a/docs/languages/images/typescript/intellisense-placeholder.png b/docs/languages/images/typescript/intellisense-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..1b033b006954435b0765871d8b5f345a02e8078d Binary files /dev/null and b/docs/languages/images/typescript/intellisense-placeholder.png differ diff --git a/docs/languages/images/typescript/intellisense.mp4 b/docs/languages/images/typescript/intellisense.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..56cf4856615534739536be236ec7e81f42fa111d --- /dev/null +++ b/docs/languages/images/typescript/intellisense.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:82919408a7df6ecf68330ce7a9561e20a8138e624372afb0e83bc7be7eca50fe +size 267340 diff --git a/docs/languages/images/typescript/jsconfigintellisense.png b/docs/languages/images/typescript/jsconfigintellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..dfc4c45f933f0e427c6a27e25443069aeb4a4c18 Binary files /dev/null and b/docs/languages/images/typescript/jsconfigintellisense.png differ diff --git a/docs/languages/images/typescript/jsdoc-autofill-placeholder.png b/docs/languages/images/typescript/jsdoc-autofill-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..cb74f2a44110b7e3b916ef1b00f2a695e553b116 Binary files /dev/null and b/docs/languages/images/typescript/jsdoc-autofill-placeholder.png differ diff --git a/docs/languages/images/typescript/jsdoc-autofill.mp4 b/docs/languages/images/typescript/jsdoc-autofill.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..e1fc5b34b47b551f5de2e23f3b5456511974cb22 --- /dev/null +++ b/docs/languages/images/typescript/jsdoc-autofill.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:63cc0bdf53dc91f1b246a0ac4c2b2b31a45a91791fda578b67a9d49d60421238 +size 199565 diff --git a/docs/languages/images/typescript/jsdocs.png b/docs/languages/images/typescript/jsdocs.png new file mode 100644 index 0000000000000000000000000000000000000000..aafa0dda95f147aae6a4f762daa378ccd2710eb1 Binary files /dev/null and b/docs/languages/images/typescript/jsdocs.png differ diff --git a/docs/languages/images/typescript/jsx-tag-complete.mp4 b/docs/languages/images/typescript/jsx-tag-complete.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..229520de3e472ccddd776ce1f8916192dd3108e1 --- /dev/null +++ b/docs/languages/images/typescript/jsx-tag-complete.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f796adde5ee1020300799715c5ebb68ec9f525ca471f7dbf28ae216604f29bdc +size 753156 diff --git a/docs/languages/images/typescript/jsx-tag-complete.png b/docs/languages/images/typescript/jsx-tag-complete.png new file mode 100644 index 0000000000000000000000000000000000000000..01e7ba5b64c109d5e14ff1f8196a8672a9f3f350 Binary files /dev/null and b/docs/languages/images/typescript/jsx-tag-complete.png differ diff --git a/docs/languages/images/typescript/jsx.png b/docs/languages/images/typescript/jsx.png new file mode 100644 index 0000000000000000000000000000000000000000..3c0fd80abd85ba14a1455e2668c2793faae53297 Binary files /dev/null and b/docs/languages/images/typescript/jsx.png differ diff --git a/docs/languages/images/typescript/organize-imports-placeholder.png b/docs/languages/images/typescript/organize-imports-placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..4e7cd32693949ded30ef806a6e67d1878cfda76b Binary files /dev/null and b/docs/languages/images/typescript/organize-imports-placeholder.png differ diff --git a/docs/languages/images/typescript/organize-imports.mp4 b/docs/languages/images/typescript/organize-imports.mp4 new file mode 100644 index 0000000000000000000000000000000000000000..7b8493a12b7c3b3b15e2005def4118875042416f --- /dev/null +++ b/docs/languages/images/typescript/organize-imports.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4f4a92e830574166a47f6910fe377fa446a4bfaf834be5282d45ce07070878e9 +size 281753 diff --git a/docs/languages/images/typescript/overview.png b/docs/languages/images/typescript/overview.png new file mode 100644 index 0000000000000000000000000000000000000000..fc3a1828b8908fbfa44f7966b05fec5d7cac65b5 --- /dev/null +++ b/docs/languages/images/typescript/overview.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3fb452e3e5648aa9056444fe01ca420de1a7a711213fffb53bb2a28319ed8d0c +size 159253 diff --git a/docs/languages/images/typescript/refactorings.png b/docs/languages/images/typescript/refactorings.png new file mode 100644 index 0000000000000000000000000000000000000000..9a371bf7f963797f59564cac7f20a86652e27bfd Binary files /dev/null and b/docs/languages/images/typescript/refactorings.png differ diff --git a/docs/languages/images/typescript/rename.png b/docs/languages/images/typescript/rename.png new file mode 100644 index 0000000000000000000000000000000000000000..222448478595435519c8a9c0c9fb560c17a1b2d8 Binary files /dev/null and b/docs/languages/images/typescript/rename.png differ diff --git a/docs/languages/images/typescript/signature-help.png b/docs/languages/images/typescript/signature-help.png new file mode 100644 index 0000000000000000000000000000000000000000..844af47ee1ff4d7b00e463ca6f8fbda82b67f1f6 Binary files /dev/null and b/docs/languages/images/typescript/signature-help.png differ diff --git a/docs/languages/images/typescript/taskSelection.png b/docs/languages/images/typescript/taskSelection.png new file mode 100644 index 0000000000000000000000000000000000000000..b3627e041a8bae2be2b756a706a6ad38d1e0e274 Binary files /dev/null and b/docs/languages/images/typescript/taskSelection.png differ diff --git a/docs/languages/images/typescript/ts-implementations-code-lens.png b/docs/languages/images/typescript/ts-implementations-code-lens.png new file mode 100644 index 0000000000000000000000000000000000000000..e73ab7b38861b59d3629a2aee386859d0c879d65 Binary files /dev/null and b/docs/languages/images/typescript/ts-implementations-code-lens.png differ diff --git a/docs/languages/images/typescript/ts-references-code-lens-peek.png b/docs/languages/images/typescript/ts-references-code-lens-peek.png new file mode 100644 index 0000000000000000000000000000000000000000..a9fbf456d9815b7c91109654d53de0e824a61d8e Binary files /dev/null and b/docs/languages/images/typescript/ts-references-code-lens-peek.png differ diff --git a/docs/languages/images/typescript/ts-references-code-lens.png b/docs/languages/images/typescript/ts-references-code-lens.png new file mode 100644 index 0000000000000000000000000000000000000000..a81d977d69830ef4336dfeebdb7eaeecc3302563 Binary files /dev/null and b/docs/languages/images/typescript/ts-references-code-lens.png differ diff --git a/docs/languages/images/typescript/typescript-build.png b/docs/languages/images/typescript/typescript-build.png new file mode 100644 index 0000000000000000000000000000000000000000..497e1fb73b33307042f1de2cae671d4546ac0e0a Binary files /dev/null and b/docs/languages/images/typescript/typescript-build.png differ diff --git a/docs/languages/images/typescript/unreachable.png b/docs/languages/images/typescript/unreachable.png new file mode 100644 index 0000000000000000000000000000000000000000..be1c076c99ca737610f427b5f7fd66108db23fed Binary files /dev/null and b/docs/languages/images/typescript/unreachable.png differ diff --git a/docs/languages/java.md b/docs/languages/java.md new file mode 100644 index 0000000000000000000000000000000000000000..5c9f34ef079d214b43dfc5c4f8150664a48b5c20 --- /dev/null +++ b/docs/languages/java.md @@ -0,0 +1,130 @@ +--- +Order: 9 +Area: languages +TOCTitle: Java +ContentId: 080fd21f-92b7-4491-9ab2-6eb9a3bb0793 +PageTitle: Java in Visual Studio Code +DateApproved: 1/2/2019 +MetaDescription: Learn about Visual Studio Code editor features (code completion, debugging, snippets, linting) for Java. +--- +# Java in Visual Studio Code + +The Java support in Visual Studio Code is provided through a wide range of [extensions](/docs/editor/extension-gallery.md). By installing extensions, you can have a lightweight and performant code editor which also supports popular Java development tools. VS Code provides essential language features such as code completion, refactoring, linting, formatting, and code snippets along with convenient debugging and unit test support. VS Code can also integrate tooling and frameworks such as Maven, Tomcat, Jetty, and Spring Boot. Leveraging the power of Visual Studio Code, Java developers get an excellent tool for both quick code editing and also the full debugging and testing cycle. It's a great choice for your Java work if you're looking for a tool which: + +- Is fast and lightweight, free, and open-source +- Supports multiple, or all the programming language you use +- Helps start your Java journey without installing and learning a complex IDE +- Provides great microservices support including popular framework, container tooling and cloud integration +- Improves your productivity through smartness and collaboration features + +This article will give you an overview of different capabilities of Visual Studio Code for Java developers. For a quick walkthrough of editing, running, and debugging a Java program with Visual Studio Code, see the [Java Tutorial](/docs/java/java-tutorial). + +> [Download VS Code](/download) - If you haven't downloaded VS Code yet, quickly install for your platform (Windows, macOS, Linux). + +## Install Java extensions + +VS Code is a fast editor and ships with great editing features. Add Java language support to VS Code by installing the popular Java extensions. To help set up Java on VS Code, there is a [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack), which contains the most popular extensions for most Java developers: + +1. [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) +2. [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) +3. [Java Test Runner](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-test) +4. [Maven for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-maven) +5. [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) +6. [Visual Studio IntelliCode](https://marketplace.visualstudio.com/items?itemName=VisualStudioExptTeam.vscodeintellicode) + +Install the Java Extension Pack + +There are also other popular Java extensions you can pick for your own needs, including: + +1. [Spring Boot Tools](https://marketplace.visualstudio.com/items?itemName=Pivotal.vscode-spring-boot) +2. [Spring Initializr Java Support](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-initializr) +3. [Spring Boot Dashboard](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-boot-dashboard) +4. [Tomcat](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) +5. [Jetty](https://marketplace.visualstudio.com/items?itemName=SummerSun.vscode-jetty) +6. [CheckStyle](https://marketplace.visualstudio.com/items?itemName=shengchen.vscode-checkstyle) + +Thanks to the great Java community around VS Code, the list doesn't end there. You can search for more Java extensions easily within VS Code: + +1. Go to the **Extensions** view (`kb(workbench.view.extensions)`). +2. Filter the extensions list by typing "java". + +![Java Extensions](images/java/extensions.png) + +This document describes some of the key features included in those Java extensions. + +## Java project support + +Maven, Eclipse, and Gradle Java projects are supported through [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java), by utilizing [M2Eclipse](https://www.eclipse.org/m2e/), which provides Maven support, and [Buildship](https://github.com/eclipse/buildship), which provides Gradle support through the [Eclipse JDT Language Server](https://github.com/eclipse/eclipse.jdt.ls). + +With [Maven for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-maven), you can generate projects from [Maven Archetype](https://maven.apache.org/guides/introduction/introduction-to-archetypes.html), browse through all the Maven projects within your workspace, and execute Maven goals easily from an embedded explorer. Projects can also be created and managed with the [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) extension. + +![Project Management](images/java/package-viewer.gif) + +More details about Java project support can be found in [Java Project Management in Visual Studio Code](/docs/java/java-project.md). + +Visual Studio Code also supports working with standalone Java files outside of a Java project, described in the [Java Tutorial with VS Code](/docs/java/java-tutorial.md). + +## Editing + +### IntelliSense + +[IntelliSense](/docs/editor/intellisense.md) is a general term for language features, including intelligent code completion (in-context method and variable suggestions) across all your files and for built-in and third-party modules. VS Code supports code completion and IntelliSense for Java through [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java). It also provides AI-assisted IntelliSense called [IntelliCode](https://visualstudio.microsoft.com/services/intellicode/) by putting what you're most likely to use at the top of your completion list. + +![IntelliSense](images/java/intellisense.gif) + +### Navigating + +Java in Visual Studio Code also supports source code navigation features such as search for symbol, Peek Definition, and Go to Definition. The [Spring Boot Tools](https://marketplace.visualstudio.com/items?itemName=Pivotal.vscode-spring-boot) extension provides enhanced navigation and code completion support for [Spring Boot](https://projects.spring.io/spring-boot/) projects. + +There are also other editing related features available for Java, such as refactoring and formatting. To learn more, read [Editing Java in Visual Studio Code](/docs/java/java-editing.md). + +## Debugging + +[Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) is a lightweight Java Debugger based on [Java Debug Server](https://github.com/Microsoft/java-debug). It works with [Language Support for Java by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) to allow users to debug Java code within Visual Studio Code. + +Starting a debugging session is easy, click on the **Run|Debug** button available at the CodeLens of your `main()` function, or press `kb(workbench.action.debug.start)`. The debugger will automatically generate the proper configuration for you. + +![Resolving Main Class](images/java/resolve-main.gif) + +Although it's lightweight, the Java debugger supports advanced features such as expression evaluation, conditional breakpoints, and hot code replacement. For more debugging related information, visit [Java Debugging](/docs/java/java-debugging.md). + +## Testing + +With the support from the [Java Test Runner](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-test) extension, you can easily run, debug, and manage your JUnit and TestNG test cases. + +![TestNG](images/java/testng.gif) + +For more about testing, read [Testing Java](/docs/java/java-testing.md). + +## Spring Boot, Tomcat, and Jetty + +To further improve your Java productivity in VS Code, there are extensions for most popular frameworks and tools such as [Spring Boot](https://projects.spring.io/spring-boot/), [Tomcat](https://tomcat.apache.org/), and [Jetty](http://www.eclipse.org/jetty/) created by the community. + +The [Tomcat](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) extension includes an explorer to easily navigate and manage your Tomcat servers. You can create, start, debug, stop, and rename your Tomcat server with the extension. + +![Tomcat](images/java/tomcat.gif) + +See [Tomcat and Jetty Support](/docs/java/java-tomcat-jetty.md) to learn more about Tomcat and Jetty support with VS Code. + +[Spring Boot](https://projects.spring.io/spring-boot/) support is provided by [Pivotal](https://marketplace.visualstudio.com/search?term=publisher%3A%22Pivotal%22&target=VSCode&category=All%20categories&sortBy=Relevance). There are also [Spring Initializr Java Support](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-initializr) and [Spring Boot Dashboard](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-spring-boot-dashboard) extensions available from Microsoft to further improve your experience with Spring Boot in Visual Studio Code. + +See [Spring Boot with VS Code](/docs/java/java-spring-boot.md) to learn more about Spring Boot support with VS Code. + +## Next steps + +Learn more about Java in VS Code + +* [Java Tutorial with VS Code](/docs/java/java-tutorial.md) +* [Code Editing and Navigation](/docs/java/java-editing.md) +* [Java Debugging](/docs/java/java-debugging.md) +* [Java Testing](/docs/java/java-testing.md) +* [Java Project Management](/docs/java/java-project.md) +* [Spring Boot with VS Code](/docs/java/java-spring-boot.md) +* [Tomcat and Jetty Support](/docs/java/java-tomcat-jetty.md) + +Read on to find out more about Visual Studio Code: + +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Tasks](/docs/editor/tasks.md) - use tasks to build your project and more +* [Debugging](/docs/editor/debugging.md) - find out how to use the debugger with your project diff --git a/docs/languages/javascript.md b/docs/languages/javascript.md new file mode 100644 index 0000000000000000000000000000000000000000..d0f4c5032272b1afd40c7dcda70c0b02569da749 --- /dev/null +++ b/docs/languages/javascript.md @@ -0,0 +1,351 @@ +--- +Order: 2 +Area: languages +TOCTitle: JavaScript +ContentId: F54BB3D4-76FB-4547-A9D0-F725CEBB905C +PageTitle: JavaScript Programming with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Get the best out of Visual Studio Code for JavaScript development +--- + +# JavaScript in Visual Studio Code + +Visual Studio Code includes built-in JavaScript IntelliSense, debugging, formatting, code navigation, refactorings, and many other advanced language features. + +![Working with JavaScript in Visual Studio Code](images/javascript/overview.png) + +Most of these features just work out of the box, while some may require basic configuration to get the best experience. This page summarizes the JavaScript features that VS Code ships with. Extensions from the [VS Code Marketplace](https://marketplace.visualstudio.com) can augment or change most of these built-in features. For a more in-depth guide on how these features work and can be configured, see [Working with JavaScript](/docs/nodejs/working-with-javascript.md). + +## IntelliSense + +IntelliSense shows you intelligent code completion, hover info, and signature information so that you can write code more quickly and correctly. + + + +VS Code provides IntelliSense within your JavaScript projects; for many npm libraries such as `React`, `lodash`, and `express`; and for other platforms such as `node`, serverless, or IoT. + +See [Working with JavaScript](/docs/nodejs/working-with-javascript.md) for information about VS Code's JavaScript IntelliSense, how to configure it, and help troubleshooting common IntelliSense problems. + +## JavaScript projects (jsconfig.json) + +A [jsconfig.json](/docs/languages/jsconfig.md) file defines a JavaScript project in VS Code. While `jsconfig.json` files are not required, you will want to create one in cases such as: + +- If not all JavaScript files in your workspace should be considered part of a single JavaScript project. `jsconfig.json` files let you exclude some files from showing up in IntelliSense. +- To ensure that a subset of JavaScript files in your workspace are treated as a single project. This is useful if you are working with legacy code that uses implicit globals dependencies instead of `imports` for dependencies. +- If your workspace contains more than one project context, such as front-end and back-end JavaScript code. For multi-project workspaces, create a `jsconfig.json` at the root folder of each project. +- You are using the TypeScript compiler to down-level compile JavaScript source code. + +To define a basic JavaScript project, add a `jsconfig.json` at the root of your workspace: + +```json +{ + "compilerOptions": { + "target": "es6" + }, + "exclude": [ + "node_modules" + ] +} +``` + +See [Working with JavaScript](/docs/nodejs/working-with-javascript.md) for more advanced `jsconfig.json` configuration. + +> **Tip:** To check if a JavaScript file is part of JavaScript project, just open the file in VS Code and run the **JavaScript: Go to Project Configuration** command. This command opens the `jsconfig.json` that the JavaScript file belongs to. A notification is shown if the file is not part of any `jsconfig.json` project. + +## Snippets + +VS Code includes basic JavaScript [snippets](/docs/editor/userdefinedsnippets.md) that are suggested as you type; + + + +There are many extensions that provide additional snippets, including snippets for popular frameworks such as Redux or Angular. You can even [define your own snippets](/docs/editor/userdefinedsnippets.md). + +> **Tip**: To disable snippets suggestions, set `editor.snippetSuggestions` to `"none"` in your [settings](/docs/getstarted/settings.md) file. The `editor.snippetSuggestions` setting also lets you change where snippets appear in the suggestions: at the top (`"top"`), at the bottom (`"bottom"`), or inlined ordered alphabetically (`"inline"`). The default is `"inline"`. + +## JS Doc support + +VS Code understands many standard [JSDoc](http://usejsdoc.org) annotations, and uses these annotations to provide rich [IntelliSense](#intellisense). You can optionally even use the type information from JSDoc comments to [type check your JavaScript](#type-checking). + + + +Quickly create JS Doc comments for functions by typing `/**` before the function declaration, and select the `JS Doc Comment` snippet suggestion: + + + +To disable JSDoc comment suggestions, set `"javascript.suggest.completeJSDocs": false`. + +## Hover Information + +Hover over a JavaScript symbol to quickly see its type information and relevant documentation. + +![Hovering over a JavaScript variable to see its type information](images/javascript/hover.png) + +The `kb(editor.action.showHover)` keyboard shortcut shows this hover info at the current cursor position. + +## Signature Help + +As you write JavaScript function calls, VS Code shows information about the function signature and highlights the parameter that you are currently completing: + +![Signature help for some DOM methods](images/javascript/signature-help.png) + +Signature help is shown automatically when you type a `(` or `,` within a function call. Press `kb(editor.action.triggerParameterHints)` to manually trigger signature help. + +## Auto imports + +Automatic imports speed up coding by suggesting available variables throughout your project and its dependencies. When you select one of these suggestions, VS Code automatically adds an import for it to the top of the file. + +Just start typing to see [suggestions](#intellisense) for all available JavaScript symbols in your current project. Auto import suggestions show where they will be imported from: + +![Global symbols are shown in the suggestion list](images/javascript/auto-import-before.png) + +If you choose one of these auto import suggestions, VS Code adds an import for it. + +In this example, VS Code adds an import for `Button` from [material-ui](https://material-ui.com) to the top of the file: + +![After selecting a symbol from a different file, an import is added for it automatically](images/javascript/auto-import-after.png) + +To disable auto imports, set `"javascript.suggest.autoImports"` to `false`. + +> **Tip:** VS Code tries to infer the best import style to use. You can explicitly configure the preferred quote style and path style for imports added to your code your code with the `javascript.preferences.quoteStyle` and `javascript.preferences.importModuleSpecifier` settings. + +## Formatting + +VS Code's built-in JavaScript formatter providers basic code formatting with reasonable defaults. + +The `javascript.format.*` [settings](/docs/getstarted/settings.md) configure the built-in formatter. Or, if the built-in formatter is getting in the way, set `"javascript.format.enable"` to `false` to disable it. + +For more specialized code formatting styles, try installing one of the JavaScript formatting extensions from the [marketplace](https://marketplace.visualstudio.com/vscode). + +## JSX and auto closing tags + +All of VS Code's JavaScript features also work with [JSX](https://reactjs.org/docs/introducing-jsx.html): + +![JSX IntelliSense](images/javascript/jsx.png) + +You can use JSX syntax in both normal `*.js` files and in `*.jsx` files. + +VS Code also includes JSX-specific features such as autoclosing of JSX tags: + + + +Set `"javascript.autoClosingTags"` to `false` to disable JSX tag closing. + +## Code navigation + +Code navigation lets you quickly navigate JavaScript projects. + +- **Go To Definition** `kb(editor.action.revealDefinition)` - Go to the source code of a symbol definition. +- **Peek Definition** `kb(editor.action.peekDefinition)` - Bring up a Peek window that shows the definition of a symbol. +- **Peek References** `kb(editor.action.referenceSearch.trigger)` - Show all references to a symbol. +- **Go to Type Definition** `kb(editor.action.goToTypeDefinition)` - Go to the type that defines a symbol. For an instance of a class, this will reveal the class itself instead of where the instance is defined. + +You can navigate via symbol search using the **Go to Symbol** commands from the **Command Palette** (`kb(workbench.action.showCommands)`). + +- **Go to Symbol in File** `kb(workbench.action.gotoSymbol)` +- **Go to Symbol in Workspace** `kb(workbench.action.showAllSymbols)` + +## Rename + +Press `kb(editor.action.rename)` to rename the symbol under the cursor across your JavaScript project: + +![Renaming a variable](images/javascript/rename.png) + +## Refactoring + +VS Code includes some handy refactorings for JavaScript such as **Extract function** and **Extract constant**. Just select the source code you'd like to extract and then click on the lightbulb in the gutter or press (`kb(editor.action.quickFix)`) to see available refactorings. + +![JavaScript refactoring](images/javascript/refactorings.png) + +Available refactorings include: + +- Extract to method or function. +- Extract to constant. +- Convert between named imports and namespace imports. +- Move to new file. + +See [Refactorings](/docs/editor/refactoring.md) for more information about refactorings and how you can configure keyboard shortcuts for individual refactorings. + +## Unused variables and unreachable code + +Unused JavaScript code, such the else block of an `if` statement that is always true or an unreferenced import, is faded out in the editor: + +![Unreachable source code faded out](images/javascript/unreachable.png) + +You can quickly remove this unused code by placing the cursor on it and triggering the Quick Fix command (`kb(editor.action.quickFix)`) or clicking on the lightbulb. + +To disable fading out of unused code, set `"editor.showUnused"` to `false`. You can also disable fading of unused code only in JavaScript by setting: + +```json +"[javascript]": { + "editor.showUnused": false +}, +"[javascriptreact]": { + "editor.showUnused": false +}, +``` + +## Organize Imports + +The **Organize Imports** Source Action sorts the imports in a JavaScript file and removes any unused imports: + + + + +You can run **Organize Imports** from the **Source Action** context menu or with the `kb(editor.action.organizeImports)` keyboard shortcut. + +Organize imports can also be automatically when you save a JavaScript file by setting: + +```json +"editor.codeActionsOnSave": { + "source.organizeImports": true +} +``` + +## Code suggestions + +VS Code automatically suggests some common code simplifications such as converting a chain of `.then` calls on a promise to use `async` and `await` + + + +Set `"javascript.suggestionActions.enabled"` to `false` to disable suggestions. + +## References CodeLens + +The JavaScript references CodeLens displays an inline count of reference for classes, methods, properties, and exported objects: + +![JavaScript references CodeLens](images/javascript/references-codelens.png) + +To enable the references code lens, set `"javascript.referencesCodeLens.enabled"` to `true`. + +Click on the reference count to quickly browse a list of references: + +![JavaScript references CodeLens peek](images/javascript/references-codelens-peek.png) + +## Update imports on file move + +When you move or rename a file that is imported by other files in your JavaScript project, VS Code can automatically update all import paths that reference the moved file: + + + +The `javascript.updateImportsOnFileMove.enabled` setting controls this behavior. Valid settings values are: + +* `"prompt"` - The default. Asks if paths should be updated for each file move. +* `"always"` - Always automatically update paths. +* `"never"` - Do not update paths automatically and do not prompt. + +## Linters + +[Linters](https://en.wikipedia.org/wiki/Lint_%28software%29) provides warnings for suspicious looking code. While VS Code does not include a built-in JavaScript linter, many JavaScript linter [extensions](/docs/editor/extension-gallery.md) available in the marketplace. + +
+ +> **Tip:** This list is dynamically queried from the [VS Code Marketplace](https://marketplace.visualstudio.com). Read the description and reviews to decide if the extension is right for you. + +## Type checking + +You can leverage some of TypeScript's advanced type checking and error reporting functionality in regular JavaScript files too. This is a great way to catch common programming mistakes. These type checks also enable some exciting Quick Fixes for JavaScript, including **Add missing import** and **Add missing property**. + +![Using type checking and Quick Fixes in a JavaScript file](images/javascript/checkjs-example.gif) + +TypeScript tried to infer types in `.js` files the same way it does in `.ts` files. When types cannot be inferred, they can be specified explicitly with JSDoc comments. You can read more about how TypeScript uses JSDocs for JavaScript type checking [here](/docs/nodejs/working-with-javascript.md). + +Type checking of JavaScript is optional and opt-in. Existing JavaScript validation tools such as ESLint can be used alongside built-in type checking functionality. + +## Debugging + +VS Code comes with great debugging support for JavaScript. Set breakpoints, inspect objects, navigate the call stack, and execute code in the Debug Console. See more about debugging [here](/docs/editor/debugging.md). + +### Debug client side + +You can debug your client-side code using a browser debugger such as [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome), [Debugger for Edge](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-edge) or [Debugger for Firefox](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-firefox-debug). + +### Debug server side + +Debug Node.js in VS Code using the built-in debugger. Setup is easy and you can read a tutorial for Node.js debugging [here](/docs/nodejs/nodejs-tutorial.md#debugging-your-express-application). + +![debug data inspection](images/javascript/debug_data_inspection.gif) + +## Popular extensions + +VS Code ships with excellent support for JavaScript but you can additionally install debuggers, snippets, linters, and other JavaScript tools through [extensions](/docs/editor/extension-gallery.md). + +
+ +> **Tip:** The extensions shown above are dynamically queried. Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com). + +## Next steps + +Read on to find out about: + +* [Working with JavaScript](/docs/nodejs/working-with-javascript.md) - More detailed information about VS Code's JavaScript support and how to troubleshoot common issues. +* [jsconfig.json](/docs/languages/jsconfig.md) - Detailed description of the `jsconfig.json` project file. +* [IntelliSense](/docs/editor/intellisense.md) - Learn more about IntelliSense and how to use it effectively for your language. +* [Debugging](/docs/editor/debugging.md) - Learn how to set up debugging for your application. +* [Node.js](/docs/nodejs/nodejs-tutorial.md) - A walkthrough to create an Express Node.js application. +* [TypeScript](/docs/languages/typescript.md) - VS Code has great support for TypeScript, which brings structure and strong typing to your JavaScript code. + +Watch these introductory videos: + +* [IntelliSense](/docs/introvideos/intellisense.md) - Tutorial on IntelliSense with JavaScript. +* [Debugging](/docs/introvideos/debugging.md) - Learn how to debug a Node.js application. + +## Common questions + +### Does VS Code support JSX and React Native? + +VS Code supports **JSX** and **React Native**. You will get IntelliSense for **React/JSX** and **React Native** from automatically downloaded type declaration (typings) files from the [npmjs](https://www.npmjs.com) type declaration file repository. Additionally, you can install the popular [React Native extension](https://marketplace.visualstudio.com/items?itemName=vsmobile.vscode-react-native) from the Marketplace. + +To enable ES6 import statements for **React Native**, you need to set the `allowSyntheticDefaultImports` compiler option to `true`. This tells the compiler to create synthetic default members and you get IntelliSense. **React Native** uses **Babel** behind the scenes to create the proper run-time code with default members. If you also want to do debugging of **React Native** code, you can install the [React Native Extension](https://marketplace.visualstudio.com/items?itemName=vsmobile.vscode-react-native). + +### IntelliSense is not working for external libraries + +`Automatic Type Acquisition` works for dependencies downloaded by npm (specified in `package.json`), Bower (specified in `bower.json`), and for many of the most common libraries listed in your folder structure (for example `jquery-3.1.1.min.js`). + +**ES6 Style imports are not working.** + +When you want to use ES6 style imports but some type declaration (typings) files do not yet use ES6 style exports, then set the [TypeScript compiler option](https://www.typescriptlang.org/docs/handbook/compiler-options.html) `allowSyntheticDefaultImports` to true. + +```javascript +{ + "compilerOptions": { + "target": "ES6", + "module": "commonjs", + // This is the line you want to add + "allowSyntheticDefaultImports": true + }, + "exclude": [ + "node_modules", + "**/node_modules/*" + ] +} +``` + +### Can I debug minified/uglified JavaScript? + +Yes, you can. You can see this working using JavaScript source maps in the [Node.js Debugging](/docs/nodejs/nodejs-debugging.md) topic. + +### How do I disable Syntax Validation when using non-ES6 constructs? + +Some users want to use syntax constructs like the proposed pipeline (`|>`) operator. However, these are currently not supported by VS Code's JavaScript language service and are flagged as errors. For users who still want to use these future features, we provide the `javascript.validate.enable` [setting](/docs/getstarted/settings.md). + +With `javascript.validate.enable: false`, you disable all built-in syntax checking. If you do this, we recommend that you use a linter like [ESLint](https://eslint.org) to validate your source code. Since VS Code's JavaScript support doesn't understand ES7 constructs, features like IntelliSense might not be fully accurate. + +### Can I use other JavaScript tools like Flow? + +Yes, but some of [Flow's](https://flow.org) language features such as type and error checking may interfere with VS Code's built-in JavaScript support. To learn how to disable VS Code's built-in JavaScript support, see [Disable JavaScript support](/docs/nodejs/working-with-javascript.md#disable-javascript-support). \ No newline at end of file diff --git a/docs/languages/jsconfig.md b/docs/languages/jsconfig.md new file mode 100644 index 0000000000000000000000000000000000000000..19e26285be5deac68ceb33277d02cc9d6408116c --- /dev/null +++ b/docs/languages/jsconfig.md @@ -0,0 +1,135 @@ +--- +Order: +Area: languages +TOCTitle: Appendix - jsconfig.json +ContentId: 201cd81d-523c-4f62-b1f5-ed26c091657b +PageTitle: jsconfig.json Reference +DateApproved: 3/7/2019 +MetaDescription: View the reference for jsconfig.json. +--- +# jsconfig.json + +## What is jsconfig.json? + +The presence of `jsconfig.json` file in a directory indicates that the directory is the root of a JavaScript Project. The `jsconfig.json` file specifies the root files and the options for the features provided by the [JavaScript language service](https://github.com/Microsoft/TypeScript/wiki/JavaScript-Language-Service-in-Visual-Studio). + +> **Tip:** If you are not using JavaScript, you do not need to worry about `jsconfig.json`. + +> **Tip:** `jsconfig.json` is a descendant of [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html), which is a configuration file for TypeScript. `jsconfig.json` is `tsconfig.json` with `"allowJs"` attribute set to `true`. + +## Why do I need a jsconfig.json file? + +Visual Studio Code's JavaScript support can run in two different modes: + +* **File Scope - no jsconfig.json**: In this mode, JavaScript files opened in Visual Studio Code are treated as independent units. As long as a file `a.js` doesn't reference a file `b.ts` explicitly (either using /// reference [directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) or **CommonJS** [modules](http://www.commonjs.org/specs/modules/1.0)), there is no common project context between the two files. + +* **Explicit Project - with jsconfig.json**: A JavaScript project is defined via a `jsconfig.json` file. The presence of such a file in a directory indicates that the directory is the root of a JavaScript project. The file itself can optionally list the files belonging to the project, the files to be excluded from the project, as well as compiler options (see below). + +The JavaScript experience is improved when you have a `jsconfig.json` file in your workspace that defines the project context. For this reason, we offer a hint to create a `jsconfig.json` file when you open a JavaScript file in a fresh workspace. + +### Location of jsconfig.json + +We define this part of our code, the client side of our website, as a JavaScript project by creating a `jsconfig.json` file. Place the file at the root of your JavaScript code as shown below. + +![jsconfig setup](images/javascript/jsconfig_setup.png) + +In more complex projects, you may have more than one `jsconfig.json` file defined inside a workspace. You will want to do this so that the code in one project is not suggested as IntelliSense to code in another project. Illustrated below is a project with a `client` and `server` folder, showing two separate JavaScript projects. + +![multiple jsconfigs](images/javascript/complex_jsconfig_setup.png) + +## Examples + +By default the JavaScript language service will analyze and provide IntelliSense for all files in your JavaScript project. You will want to specify which files to exclude or include in order to provide the proper IntelliSense. + +### Using the `"exclude"` property + +The `exclude` attribute (a glob pattern) tells the language service what files are and are not part of your source code. This keeps performance at a high level. If IntelliSense is slow, add folders to your `exclude` list (VS Code will prompt you to do this if it detects the slow down). + +```json +{ + "compilerOptions": { + "target": "es6" + }, + "exclude": [ + "node_modules" + ] +} +``` + +> **Tip:** You will want to `exclude` files generated by a build process (for example, a `dist` directory). These files will cause suggestions to show up twice and will slow down IntelliSense. + +### Using the `"include"` property + +Alternatively, you can explicitly set the files in your project using the `include` attribute (a glob pattern). If no `include` attribute is present, then this defaults to including all files in the containing directory and subdirectories. When a `include` attribute is specified, only those files are included. Here is an example with an explicit `include` attribute. + +```json +{ + "compilerOptions": { + "target": "es6" + }, + "include": [ + "src/**/*" + ] +} +``` + +> **Tip:** The file paths in `exclude` and `include` are relative to the location of `jsconfig.json`. + +## jsconfig Options + +Below are `jsconfig` `"compilerOptions"` to configure the JavaScript language support. + +> **Tip:** Do not be confused by `compilerOptions`. This attribute exists because `jsconfig.json` is a descendant of `tsconfig.json`, which is used for compiling TypeScript. + +Option | Description +----------------|----- +`noLib` | Do not include the default library file (lib.d.ts) +`target`| Specifies which default library (lib.d.ts) to use. The values are "es3", "es5", "es6", "es2015", "es2016", "es2017", "es2018", "esnext". +`checkJs` | Enable type checking on JavaScript files. +`experimentalDecorators`|Enables experimental support for proposed ES decorators. +`allowSyntheticDefaultImports`|Allow default imports from modules with no default export. This does not affect code emit, just type checking. +`baseUrl`|Base directory to resolve non-relative module names. +`paths`|Specify path mapping to be computed relative to baseUrl option. + +## Using webpack aliases + +For IntelliSense to work with webpack aliases, you need to specify the `paths` keys with a glob pattern. + +For example, for alias 'ClientApp': + +```json +{ + "compilerOptions": { + "baseUrl": ".", + "paths": { + "ClientApp/*": ["./ClientApp/*"] + } + } +} +``` + +and then to use the alias + +```js +import Something from 'ClientApp/foo' +``` + +## Best Practices + +Whenever possible, you should exclude folders with JavaScript files that are not part of the source code for your project. + +>**Tip:** If you do not have a `jsconfig.json` in your workspace, VS Code will by default exclude the `node_modules` folder. + +Below is a table mapping common project components to their installation folders which are recommended to exclude: + +Component | folder to exclude +----------|----------- +`node` | exclude the `node_modules` folder +`webpack`, `webpack-dev-server` | exclude the content folder, e.g., `dist`. +`bower` | exclude the `bower_components` folder +`ember` | exclude the `tmp` and `temp` folders +`jspm` | exclude the `jspm_packages` folder + +When your JavaScript project is growing too large and performance slows, it is often because of library folders like `node_modules`. If VS Code detects that your project is growing too large, it will prompt you to edit the `exclude` list. + +>**Tip:** Sometimes changes to configuration, such as adding or editing a `jsconfig.json` file are not picked up correctly. Running the **Reload JavaScript Project** command should reload the project and pick up the changes. \ No newline at end of file diff --git a/docs/languages/json.md b/docs/languages/json.md new file mode 100644 index 0000000000000000000000000000000000000000..725c3f18c8e775295c3805059729921af095f68f --- /dev/null +++ b/docs/languages/json.md @@ -0,0 +1,164 @@ +--- +Order: 3 +Area: languages +TOCTitle: JSON +ContentId: FB3B14D9-A59A-4968-ACFC-5FB5D4E9B70E +PageTitle: JSON editing in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Edit JSON files in Visual Studio Code +--- +# Editing JSON with Visual Studio Code + +JSON is a data format that is common in configuration files like `package.json` or `project.json`. We also use it extensively in Visual Studio Code for our configuration files. When opening a file that ends with `.json`, VS Code provides features out of the box to make it simpler to write or modify the file's content. + +![JSON within VS Code](images/json/json_hero.png) + +## IntelliSense & Validation + +For properties and values, both for JSON data with and without a schema, we offer up suggestions as you type with IntelliSense. You can also manually see suggestions with the **Trigger Suggestions** command (`kb(editor.action.triggerSuggest)`). We also perform structural and value verification based on an associated JSON schema giving you red squiggles. + +![IntelliSense](images/json/intellisense.png) + +### Package and Project Dependencies + +We also offer IntelliSense for specific value sets such as package and project dependencies in `package.json`, `project.json` and `bower.json`. + +## Quick Navigation + +JSON files can get pretty large and we support quick navigation to properties the **Go to Symbol** command (`kb(workbench.action.gotoSymbol)`). + +![Goto Symbol](images/json/gotosymbol.png) + +## Hovers + +When you hover over properties and values for JSON data with or without schema, we will provide additional context. + +![Hover](images/json/hoverandtoggle.png) + +## Formatting + +You can format your JSON document using `kb(editor.action.formatDocument)` or **Format Document** from the context menu. + +## Folding + +You can fold regions of source code using the folding icons on the gutter between line numbers and line start. Folding ranges are available for all object and array elements. + +## JSON with Comments + +In addition to the default JSON mode following the [JSON specification](https://www.json.org/), VS Code also has a **JSON with Comments** mode . This mode is used for the VS Code configuration files such as `settings.json`, `tasks.json` or `launch.json`. When in the **JSON with Comments** mode, you can use single line (//) as well as block comments (/* */) as used in JavaScript. The current editor mode is indicated in the editor's Status Bar. Click on the mode indicator to change the mode and to configure how file names and extensions are associated to modes. + +## JSON Schemas & Settings + +To understand the structure of JSON files, we use [JSON schemas](http://json-schema.org/). JSON schemas describe the shape of the JSON file, as well as value sets, default values, and descriptions. The JSON support shipped with VS Code supports JSON Schema Draft 7. + +Servers like [JSON Schema Store](http://schemastore.org) provide schemas for most of the common JSON based configuration files. However, schemas can also be defined in a file in the VS Code workspace, as well as the VS Code settings files. + +The association of a JSON file to a schema can be done either in the JSON file itself using the `$schema` attribute, or in the User or Workspace [settings](/docs/getstarted/settings.md) (**File** > **Preferences** > **Settings**) under the property `json.schemas`. + +VS Code extensions can also define schemas and schema mapping. That's why VS Code already knows about the schema of some well known JSON files such as `package.json`, `bower.json` and `tsconfig.json`. + +### Mapping in the JSON + +In the following example, the JSON file specifies that its contents follow the [CoffeeLint](http://www.coffeelint.org/) schema. + +```json +{ + "$schema": "http://json.schemastore.org/coffeelint", + "line_endings": "unix" +} +``` + +Please note that this syntax is VS Code-specific and not part of the [JSON Schema specification](http://json-schema.org/latest/json-schema-core.html#rfc.section.7). Adding the `$schema` key changes the JSON itself, which systems consuming the JSON might not expect, for example, schema validation might fail. If this is the case, you can use one of the other mapping methods. + +### Mapping in the User Settings + +The following excerpt from User [settings](/docs/getstarted/settings.md) shows how `.babelrc` files are mapped to the [babelrc](https://babeljs.io/docs/usage/babelrc) schema located on [http://json.schemastore.org/babelrc](http://json.schemastore.org/babelrc). + +```json +"json.schemas": [ + { + "fileMatch": [ + "/.babelrc" + ], + "url": "http://json.schemastore.org/babelrc" + }, +``` + +>**Tip:** Additionally to defining a schema for `.babelrc`, also make sure that `.babelrc` is associated to the JSON language mode. This is also done in the settings using the `files.association` array setting. + +### Mapping to a Schema in the Workspace + +To map a schema that is located in the workspace, use a relative path. In this example, a file in the workspace root called `myschema.json` will be used as the schema for all files ending with `.foo.json`. + +```json +"json.schemas": [ + { + "fileMatch": [ + "/*.foo.json" + ], + "url": "./myschema.json" + }, +``` + +### Mapping to a Schema Defined in Settings + +To map a schema that is defined in the User or Workspace settings, use the `schema` property. In this example, a schema is defined that will be used for all files named `.myconfig`. + +```json +"json.schemas": [ + { + "fileMatch": [ + "/.myconfig" + ], + "schema": { + "type": "object", + "properties": { + "name" : { + "type": "string", + "description": "The name of the entry" + } + } + } + }, +``` + +### Mapping a Schema in an Extension + +Schemas and schema associations can also be defined by an extension. Check out the [jsonValidation contribution point](/api/references/contribution-points.md#contributes.jsonValidation). + +### Define Snippets in JSON Schemas + +JSON schemas describe the shape of the JSON file, as well as value sets and default values which are used by the JSON language support to provide completion proposals. If you are a schema author and want to provide even more customized completion proposals, you can also specify snippets in the schema. + +The following example shows a schema for a key binding settings file defining a snippet: + +```json +{ + "type": "array", + "title": "Keybindings configuration", + "items": { + "type": "object", + "required": ["key"], + "defaultSnippets": [ + { + "label": "New keybinding", + "description": "Binds a key to a command for a given state", + "body": { "key": "$1", "command": "$2", "when": "$3" } + } + ], + "properties": { + "key": { + "type": "string" + } + ... + } + } +}; +``` + +Use the property `defaultSnippets` to specify any number of snippets for the given JSON object. + +- `label` and `description` will be shown in the completion selection dialog. If no label is provided, a stringified object representation of the snippet will be shown as label instead. +- `body` is the JSON object that is stringified and inserted when the completion is selected by the user. [Snippet syntax](/docs/editor/userdefinedsnippets.md#snippet-syntax) can be used inside strings literals to define tabstops, placeholders and variables. If a string starts with `^`, the string content will be inserted as-is, not stringified. You can use this to specify snippets for numbers and booleans. + +Note that `defaultSnippets` is not part of the JSON schema spec but a VS Code specific schema extension. diff --git a/docs/languages/markdown.md b/docs/languages/markdown.md new file mode 100644 index 0000000000000000000000000000000000000000..87b869c6aef873da3591d9842644580cb3f0ba0b --- /dev/null +++ b/docs/languages/markdown.md @@ -0,0 +1,325 @@ +--- +Order: 7 +Area: languages +TOCTitle: Markdown +ContentId: 47A8BA5A-A103-4B61-B5FB-185C15E54C52 +PageTitle: Markdown editing with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Get the best out of Visual Studio Code for Markdown +--- +# Markdown and Visual Studio Code + +Working with Markdown files in Visual Studio Code is simple, straightforward, and fun. Besides VS Code's basic editing, there are a number of Markdown specific features that will help you be more productive. + +## Markdown extensions + +In addition to the functionality VS Code provides out of the box, you can install an extension for greater functionality. + +
+ +> Tip: Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com). + +## Markdown preview + +VS Code supports Markdown files out of the box. You just start writing Markdown text, save the file with the .md extension and then you can toggle the visualization of the editor between the code and the preview of the Markdown file; obviously, you can also open an existing Markdown file and start working with it. To switch between views, press `kb(markdown.showPreview)` in the editor. You can view the preview side-by-side (`kb(markdown.showPreviewToSide)`) with the file you are editing and see changes reflected in real-time as you edit. + +Here is an example with a very simple file. + +![Markdown Preview](images/Markdown/preview.png) + +>**Tip:** You can also right-click on the editor Tab and select **Open Preview to the Side** or use the **Command Palette** (`kb(workbench.action.showCommands)`) to run the **Markdown: Open Preview to the Side** command. + +### Dynamic previews and preview locking + +By default, Markdown previews automatically update to preview the currently active Markdown file: + +![The preview automatically switching to preview the current Markdown document](images/Markdown/md-dynamic-preview.gif) + +You can lock a Markdown preview using the **Markdown: Toggle Preview Locking** command to keep it locked to its current Markdown document. Locked previews are indicated by **[Preview]** in the title: + +![A locked markdown preview](images/Markdown/locked-preview-title.png) + +### Editor and preview synchronization + +VS Code automatically synchronizes the Markdown editor and the preview views. Scroll the Markdown preview and the editor is scrolled to match the preview's viewport. Scroll the Markdown editor and the preview is scrolled to match its viewport: + +![Markdown Preview editor selection scroll sync](images/Markdown/preview-scroll-sync.gif) + +You can disable scroll synchronization using the `markdown.preview.scrollPreviewWithEditor` and `markdown.preview.scrollEditorWithPreview` [settings](/docs/getstarted/settings.md). + +The currently selected line in the editor is indicated in the Markdown preview by a light gray bar in the left margin: + +![Markdown Preview editor line marker](images/Markdown/preview-selection-marker.png) + +Additionally, double clicking an element in the Markdown preview will automatically open the editor for the file and scroll to the line nearest the clicked element. + +![Markdown Preview double click switches to editor](images/Markdown/double-click-preview-switch.gif) + +## Outline view + +The Outline view is a separate section in the bottom of the File Explorer. When expanded, it will show the symbol tree of the currently active editor. For Markdown files, the symbol tree is the Markdown file's header hierarchy. + +![Markdown Outline view](images/Markdown/markdown-outline-view.png) + +The Outline view is a great way to review your document's header structure and outline. + +## Extending the Markdown preview + +Extensions can contribute custom styles and scripts to the Markdown preview to change its appearance and add new functionality. Here's a set of example extensions that customize the preview: + +
+ +### Using your own CSS + +You can also use your own CSS in the Markdown preview with the `"markdown.styles": []` [setting](/docs/getstarted/settings.md). This lists URLs for style sheets to load in the Markdown preview. These stylesheets can either be `https` URLs, or relative paths to local files in the current workspace. + +For example, to load a stylesheet called `Style.css` at the root of your current workspace, use **File** > **Preferences** > **Settings** to bring up the workspace `settings.json` file and make this update: + +```json +// Place your settings in this file to overwrite default and user settings. +{ + "markdown.styles": [ + "Style.css" + ] +} +``` + +## Markdown preview security + +For security reasons, VS Code restricts the content displayed in the Markdown preview. This includes disabling script execution and only allowing resources to be loaded over `https`. + +When the Markdown preview blocks content on a page, an alert popup is shown in the top right corner of the preview window: + +![markdown security alert](images/Markdown/security-alert.png) + +You can change what content is allowed in the Markdown preview by clicking on this popup or running the **Markdown: Change preview security settings** command in any Markdown file: + +![markdown security selector](images/Markdown/security-selector.png) + +The Markdown preview security settings apply to all files in the workspace. + +Here are the details about each of these security levels: + +### Strict + +This is the default setting. Only loads trusted content and disables script execution. Blocks `http` images and all SVG images not from one of our [trusted badge providers](/api/references/extension-manifest.md#approved-badges). + +It is strongly recommended that you keep `Strict` security enabled unless you have a very good reason to change it AND you trust all markdown files in the workspace. + +### Allow insecure content + +Keeps scripts disabled but allows content to be loaded over `http`. Also enables SVG images. + +### Disable + +Disables additional security in the preview window. This allows script execution and also allows content to be loaded over `http`. + +## Snippets for Markdown + +There are several built-in Markdown snippets included in VS Code - press `kb(editor.action.triggerSuggest)` (Trigger Suggest) and you get a context specific list of suggestions. + +>**Tip:** You can add in your own User Defined Snippets for Markdown. Take a look at [User Defined Snippets](/docs/editor/userdefinedsnippets.md) to find out how. + +## Compiling Markdown into HTML + +VS Code integrates with Markdown compilers through the integrated [task runner](/docs/editor/tasks.md). We can use this to compile `.md` files into `.html` files. Let's walk through compiling a simple Markdown document. + +### Step 1: Install a Markdown compiler + +For this walkthrough, we use the popular [Node.js](https://nodejs.org) module, [markdown-it](https://github.com/markdown-it/markdown-it). + +```bash +npm install -g markdown-it +``` + +> **Note:** There are many Markdown compilers to choose from beyond **markdown-it**. Pick the one that best suits your needs and environment. + +### Step 2: Create a simple MD file + +Open VS Code on an empty folder and create a `sample.md` file. + +> **Note:** You can open a folder with VS Code by either selecting the folder with **File** > **Open Folder** or navigating to the folder and typing 'code .' at the command line. + +Place the following source code in that file: + +```markdown +# Hello Markdown in VS Code! + +This is a simple introduction to compiling Markdown in VS Code. + +Things you'll need: + +* [Node.js](https://nodejs.org) +* [markdown-it](https://www.npmjs.com/package/markdown-it) +* [tasks.json](/docs/editor/tasks.md) + +## Section Title + +> This block quote is here for your information. +``` + +### Step 3: Create tasks.json + +The next step is to set up the task configuration file `tasks.json`. To do this, run **Terminal** > **Configure Tasks** and click **Create tasks.json file from templates**. VS Code then presents a list of possible `tasks.json` templates to choose from. Select **Others** since we want to run an external command. + +This generates a `tasks.json` file in your workspace `.vscode` folder with the following content: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "echo", + "type": "shell", + "command": "echo Hello" + } + ] +} +``` + +To use **markdown-it** to compile the Markdown file, change the contents as follows: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "Compile Markdown", + "type": "shell", + "command": "markdown-it sample.md -o sample.html", + "group": "build" + } + ] +} +``` + +> **Tip:** While the sample is there to help with common configuration settings, IntelliSense is available for the `tasks.json` file as well to help you along. Use `kb(editor.action.triggerSuggest)` to see the available settings. + +### Step 4: Run the Build Task + +Since in more complex environments there can be more than one build task we prompt you to pick the task to execute after pressing `kb(workbench.action.tasks.build)` (**Run Build Task**). In addition, we allow you to scan the output for compile problems. Since we only want to convert the Markdown file to HTML select **Never scan the build output** from the presented list. + +At this point, you should see an additional file show up in the file list `sample.html`. + +If you want to make the **Compile Markdown** task the default build task to run execute **Configure Default Build Task** from the global **Terminal** menu and select **Compile Markdown** from the presented list. The final `tasks.json` file will then look like this: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "Compile Markdown", + "type": "shell", + "command": "markdown-it sample.md -o sample.html", + "problemMatcher": [], + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} +``` + +## Automating Markdown compilation + +Let's take things a little further and automate Markdown compilation with VS Code. We can do so with the same task runner integration as before, but with a few modifications. + +### Step 1: Install Gulp and some plug-ins + +We use [Gulp](https://gulpjs.com/) to create a task that automates Markdown compilation. We also use the [gulp-markdown](https://www.npmjs.com/package/gulp-markdown) plug-in to make things a little easier. + +We need to install gulp both globally (`-g` switch) and locally: + +``` +npm install -g gulp +npm install gulp gulp-markdown-it +``` + +> **Note:** gulp-markdown-it is a Gulp plug-in for the **markdown-it** module we were using before. There are many other Gulp Markdown plug-ins you can use, as well as plug-ins for Grunt. + +You can test that your gulp installation was successful but typing `gulp -v`. You should see a version displayed for both the global (CLI) and local installations. + +### Step 2: Create a simple Gulp task + +Open VS Code on the same folder from before (contains `sample.md` and `tasks.json` under the `.vscode` folder), and create `gulpfile.js` at the root. + +Place the following source code in that file: + +```javascript +var gulp = require('gulp'); +var markdown = require('gulp-markdown-it'); + +gulp.task('markdown', function() { + return gulp.src('**/*.md') + .pipe(markdown()) + .pipe(gulp.dest(function(f) { + return f.base; + })); +}); + +gulp.task('default', ['markdown'], function() { + gulp.watch('**/*.md', ['markdown']); +}); +``` + +What is happening here? + +1. We are watching for changes to any Markdown file in our workspace, i.e. the current folder open in VS Code. +2. We take the set of Markdown files that have changed, and run them through our Markdown compiler, i.e. `gulp-markdown-it`. +3. We now have a set of HTML files, each named respectively after their original Markdown file. We then put these files in the same directory. + +### Step 3: Run the gulp default Task + +To complete the tasks integration with VS Code, we will need to modify the task configuration from before to run the default Gulp task we just created. You can either delete the `tasks.json` file or empty it only keeping the `"version": "2.0.0"` property. Now execute **Run Task** from the global **Terminal** menu. Observe that you are presented with a picker listing the tasks defined in the gulp file. Select **gulp: default** to start the task. We allow you to scan the output for compile problems. Since we only want to convert the Markdown file to HTML select **Never scan the build output** from the presented list. At this point, if you create and/or modify other Markdown files, you see the respective HTML files generated and/or changes reflected on save. You can also enable [Auto Save](/docs/editor/codebasics.md#saveauto-save) to make things even more streamlined. + +If you want to make the **gulp: default** task the default build task executed when pressing `kb(workbench.action.tasks.build)` run **Configure Default Build Task** from the global **Terminal** menu and select **gulp: default** from the presented list. The final `tasks.json` file will then look like this: + +```json +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "type": "gulp", + "task": "default", + "problemMatcher": [], + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} +``` + +### Step 4: Terminate the gulp default Task + +The **gulp: default** task runs in the background and watches for file changes to Markdown files. If you want to stop the task, you can use the **Terminate Task** from the global **Terminal** menu. + +## Next steps + +Read on to find out about: + +* [CSS, SCSS, and Less](/docs/languages/css.md) - Want to edit your CSS? VS Code has great support for CSS, SCSS, and Less editing. + +## Common questions + +### Is there spell checking? + +Not installed with VS Code but there are spell checking extensions. Check the [VS Code Marketplace](https://marketplace.visualstudio.com/vscode) to look for useful extensions to help with your workflow. + +### Does VS Code support GitHub Flavored Markdown? + +No, VS Code targets the [CommonMark](http://commonmark.org) Markdown specification using the [markdown-it](https://github.com/markdown-it/markdown-it) library. GitHub is moving toward the CommonMark specification which you can read about in this [update](https://githubengineering.com/a-formal-spec-for-github-markdown). + +### In the walkthrough above, I didn't find the Configure Task command in the Command Palette? + +You may have opened a file in VS Code rather than a folder. You can open a folder by either selecting the folder with **File** > **Open Folder** or navigating to the folder and typing 'code .' at the command line. diff --git a/docs/languages/overview.md b/docs/languages/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..c3eb84a79aa9803ea1147e3c892105b81bb92a55 --- /dev/null +++ b/docs/languages/overview.md @@ -0,0 +1,127 @@ +--- +Order: 1 +Area: languages +TOCTitle: Overview +ContentId: AC888642-FBE5-43E5-9DC2-47B197717940 +PageTitle: Language Support in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: In Visual Studio Code we have support for all common languages including smart code completion and debugging. +--- +# Programming Languages + +## Hundreds of programming languages supported + +In Visual Studio Code, we have support for almost every major programming language. Several ship in the box, for example, JavaScript, TypeScript, CSS, and HTML but more rich language extensions can be found in the [VS Code Marketplace](https://marketplace.visualstudio.com/vscode/Languages). + +Here are eight of the most popular language extensions: + +
+ +Go to the [Marketplace](https://marketplace.visualstudio.com/vscode) or use our [integrated extension manager](/docs/editor/extension-gallery) and search for your desired programming language to find snippets, code completion/IntelliSense providers, linters, debuggers and more. + +>**Note**: If you want to change the display language of VS Code (for example, to Chinese), see the [Display Language](/docs/getstarted/locales.md) topic. + +## Language specific documentation + +On this website, we have a number of topics outlining several of the common languages supported by VS Code. These include: [C++](/docs/languages/cpp.md) - [C#](/docs/languages/csharp.md) - [CSS](/docs/languages/css.md) - [Dockerfile](/docs/azure/docker.md) - [Go](/docs/languages/go.md) - [HTML](/docs/languages/html.md) - [Java](/docs/languages/java.md) - [JavaScript](/docs/languages/javascript.md) - [JSON](/docs/languages/json.md) - [Less](/docs/languages/css.md) - +[Markdown](/docs/languages/markdown.md) - [PHP](/docs/languages/php.md) - [PowerShell](/docs/languages/powershell.md) - [Python](/docs/languages/python.md) - [SCSS](/docs/languages/css.md) - [T-SQL](/docs/languages/tsql.md) - [TypeScript](/docs/languages/typescript.md). + +Click on any linked item to get an overview of how to use VS Code in the context of that language. Most language extensions also contain a summary of their core features in their README. + +## Language features in VS Code + +The richness of support varies across the different languages and their extensions: + +* Syntax highlighting and bracket matching +* Smart completions (IntelliSense) +* Linting and corrections +* Code navigation (Go to Definition, Find All References) +* Debugging +* Refactoring + +## Changing the language for the selected file + +In VS Code, we default the language support for a file based on its filename extension. However, at times you may wish to change language modes, to do this click on the language indicator - which is located on the right hand of the Status Bar. This will bring up the **Select Language Mode** drop-down where you can select another language for the current file. + +![Language Selector](images/overview/languageselect.png) + +**Tip**: You can get the same drop-down by running the **Change Language Mode** command (`kb(workbench.action.editor.changeLanguageMode)`). + +## Language Id + +VS Code associates a language mode with a specific language identifier so that various VS Code features can be enabled based on the current language mode. + +A language identifier is often (but not always) the lowercased programming language name. Note that casing matters for exact identifier matching ('Markdown' != 'markdown'). Unknown language files have the language identifier `plaintext`. + +You can see the list of currently installed languages and their identifiers in the **Change Language Mode** (`kb(workbench.action.editor.changeLanguageMode)`) drop-down. + +![language identifiers](images/overview/language-identifiers.png) + +You can find a list of known identifiers in the [language identifier reference](/docs/languages/identifiers.md). + +## Adding a file extension to a language + +You can add new file extensions to an existing language with the `files.associations` [setting](/docs/getstarted/settings.md). + +For example, the setting below adds the `.myphp` file extension to the `php` language identifier: + +```json + "files.associations": { + "*.myphp": "php" + } +``` + +IntelliSense (`kb(editor.action.triggerSuggest)`) will show you the available language identifiers. + +![language id IntelliSense](images/overview/language-id-intellisense.png) + +## Next steps + +Now you know that VS Code has support for the languages you care about. Read on... + +* [Code Navigation](/docs/editor/editingevolved.md) - Peek and Go to Definition and more +* [Debugging](/docs/editor/debugging.md) - This is where VS Code really shines + +## Common questions + +### Can I contribute my own language service? + +Yes you can! Check out the [example language server](/api/language-extensions/language-server-extension-guide.md) in the [VS Code Extension API](/api) documentation. + +### What if I don't want to create a full language service, can I reuse existing TextMate bundles? + +Yes, you can also add support for your favorite language through TextMate colorizers. See the [Syntax Highlight Guide](/api/language-extensions/syntax-highlight-guide.md) in the Extension API section to learn how to integrate TextMate `.tmLanguage` syntax files into VS Code. + +### Can I map additional file extensions to a language? + +Yes, with the `files.associations` [setting](/docs/getstarted/settings.md) you can map file extensions to an existing language either globally or per workspace. + +Here is an example that will associate more file extensions to the PHP language: + +```json +"files.associations": { + "*.php4": "php", + "*.php5": "php" +} +``` + +You can also configure full file paths to languages if needed. The following example associates all files in a folder `somefolder` to PHP: + +```json +"files.associations": { + "**/somefolder/*.*": "php" +} +``` + +Note that the pattern is a [glob pattern](https://en.wikipedia.org/wiki/Glob_%28programming%29) that will match on the full path of the file if it contains a `/` and will match on the file name otherwise. + +### How do I set the default language for new files? + +Using the `files.defaultLanguage` [setting](/docs/getstarted/settings.md), you can map all new files to a default language. Whenever a new blank file is opened, the editor will be configured for that language mode. + +This example will associate new files with the HTML language: + +```json + // The default language mode that is assigned to new files. + "files.defaultLanguage": "html" +``` diff --git a/docs/languages/php.md b/docs/languages/php.md new file mode 100644 index 0000000000000000000000000000000000000000..274542cfd914e0cb31e62b46a69dbea1ab3194e4 --- /dev/null +++ b/docs/languages/php.md @@ -0,0 +1,73 @@ +--- +Order: 10 +Area: languages +TOCTitle: PHP +ContentId: DD4E5A59-1586-4A5D-8047-3D58B2FE6937 +PageTitle: PHP Programming with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Learn about Visual Studio Code editor features (syntax highlighting, snippets, linting) and extensions for PHP. +--- +# PHP in Visual Studio Code + +Visual Studio Code is a great editor for PHP development. You get features like syntax highlighting and bracket matching, IntelliSense (code completion), and snippets out of the box and you can add more functionality through community-created VS Code [extensions](/docs/editor/extension-gallery.md). + +## PHP extensions + +There are many PHP language extensions available on the [VS Code Marketplace](https://marketplace.visualstudio.com/VSCode) and more are being created. You can search for PHP extensions from within VS Code in the **Extensions** view (`kb(workbench.view.extensions)`) then filter the extensions drop-down list by typing `php`. + +
+ +> Tip: The extensions shown above are dynamically queried. Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com). + +> Tip: The following [setting](/docs/getstarted/settings.md) allows to disable the built-in PHP completions in favor of proposals created by installed PHP extensions. + +- `php.suggest.basic`: Configures if the built-in PHP language suggestions are enabled. Enabled by default. + +## Snippets + +Visual Studio Code includes a set of common snippets for PHP. To access these, hit `kb(editor.action.triggerSuggest)` to get a context-specific list. + +![PHP Snippets](images/php/php-snippets.png) + +## Linting + +VS Code uses the official PHP linter (`php -l`) for PHP language diagnostics. This allows VS Code to stay current with PHP linter improvements. + +> Tip: Using XAMPP? Install the full version of PHP in order to obtain the development libraries. + +There are three [settings](/docs/getstarted/settings.md) to control the PHP linter: + +* `php.validate.enable`: controls whether to enable PHP linting at all. Enabled by default. +* `php.validate.executablePath`: points to the PHP executable on disk. Set this if the PHP executable is not on the system path. +* `php.validate.run`: controls whether the validation is triggered on save (value: `"onSave"`) or on type (value: `"onType"`). Default is on save. + +![show PHP settings](images/php/php-settings.png) + +To set the PHP executable path, open your **User or Workspace Settings** and add the `php.validate.executablePath`: + +### Windows + +```json +{ + "php.validate.executablePath": "c:/php/php.exe" +} +``` + +### Linux and macOS + +```json +{ + "php.validate.executablePath": "/usr/bin/php" +} +``` + +## Debugging + +PHP debugging with **XDebug** is supported through a [PHP Debug extension](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug). Follow the extension's instructions for configuring **XDebug** to work with VS Code. + +## Next steps + +Read on to find out about: + +* [Extension Marketplace](/docs/editor/extension-gallery.md) - Browse the extensions others have shared +* [Debugging](/docs/editor/debugging.md) - Learn more about VS Code debugging diff --git a/docs/languages/powershell.md b/docs/languages/powershell.md new file mode 100644 index 0000000000000000000000000000000000000000..1a8e865e3295e17a01314ed0b49dd01bb20b334b --- /dev/null +++ b/docs/languages/powershell.md @@ -0,0 +1,206 @@ +--- +Order: 8 +Area: languages +TOCTitle: PowerShell +ContentId: 8688bb6d-793e-4a37-aed2-5af4cfe89940 +PageTitle: PowerShell editing with Visual Studio Code +DateApproved: 9/17/2018 +MetaDescription: Learn about using PowerShell in Visual Studio Code +--- +# PowerShell in Visual Studio Code + +[PowerShell](https://docs.microsoft.com/powershell/) is a task-based command-line shell and scripting language built on [.NET](https://docs.microsoft.com/dotnet), which provides a powerful toolset for administrators on any platform. + +The Microsoft [PowerShell](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell) extension for Visual Studio Code provides rich language support and capabilities such as completions, definition tracking, and linting analysis for PowerShell versions 3, 4, 5, and 5.1 as well as all versions of [PowerShell Core](https://docs.microsoft.com/powershell/scripting/whats-new/what-s-new-in-powershell-core-60). + +## Install the PowerShell extension + +The official PowerShell extension can be installed by following the steps described in the +[Visual Studio Code User Guide](/docs/editor/extension-gallery.md) or by going directly to the Visual Studio Code Marketplace and clicking the [Install Button](vscode:extension/ms-vscode.PowerShell). + +You can also install the PowerShell extension from within Visual Studio Code by opening the Extensions view with keyboard shortcut `kb(workbench.view.extensions)` and typing "PowerShell" and select the PowerShell extension: + +![PowerShell extension](images/powershell/PowerShellExtension.png) + +## Install from the command line + +Alternatively, the PowerShell extension can be installed from any command line (including PowerShell, Cmd, bash) on all platforms with the following command + +```bash +code --install-extension ms-vscode.powershell +``` + +If you are running VS Code [Insiders](/insiders), you will need this command instead: + +```bash +code-insiders --install-extension ms-vscode.powershell +``` + +## Example scripts + +Example scripts are included with the extension and can be found at the following path. + + C:\Users\\.vscode\extensions\ms-vscode.PowerShell-\examples + +To open or view the examples in Visual Studio Code, run the following from your PowerShell command prompt: + +```bash +code (Get-ChildItem $Home\.vscode\extensions\ms-vscode.PowerShell-*\examples)[-1] +``` + +If using the [Insiders](/insiders) edition: + +```bash +code-insiders (Get-ChildItem $Home\.vscode\extensions\ms-vscode.PowerShell-*\examples)[-1] +``` + +You can also open the examples from the Command Palette (`kb(workbench.action.showCommands)`) with the **PowerShell: Open Examples Folder** command. + +![Open PowerShell Examples](images/powershell/pwshExamples.png) + +## Major features + +* Syntax highlighting +* Code snippets +* IntelliSense for cmdlets and more +* Rule-Based analysis provided by PowerShell Script Analyzer +* "Go to definition" of cmdlets and variables +* Find references of cmdlets and variables +* Document and Workspace symbol discovery +* Run selected section of PowerShell code using `kbstyle(F8)` +* Launch online help for the symbol under the cursor using `kbstyle(Ctrl + F1)` +* Local script debugging and basic interactive console support + +## Debugging + +The PowerShell extension uses the built-in debugging interface of VS Code to allow for debugging of PowerShell scripts and modules. You can learn more about [VS Code debugging](/docs/editor/debugging.md) here. + +### Hey, Scripting Guy! blog + +![HSG](images/powershell/HSGavatar.png) + +For more information on debugging, check out the "Hey, Scripting Guy!" two-part blog post series written by [@keithHill](https://twitter.com/r_keith_hill) on debugging with the PowerShell extension: + +[Debugging PowerShell script in Visual Studio Code – Part 1](https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/06/debugging-powershell-script-in-visual-studio-code-part-1/) + +[Debugging PowerShell script in Visual Studio Code – Part 2](https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/13/debugging-powershell-script-in-visual-studio-code-part-2/) + +## PowerShell extension settings + +You can customize VS Code [settings](/docs/getstarted/settings.md) from the **File** > **Preferences** > **Settings** menu item (**Code** > **Preferences** > **Settings** on macOS). + +You can also click the gear icon located in the lower left corner of the Activity Bar. + +![codeGear](images/powershell/codeGear.png) + +You can also use the keyboard shortcut `kb(workbench.action.openSettings)` to open your settings. The VS Code team has introduced a settings GUI in the latest version 1.27.1 as the new default interface for customizing settings. In VS Code versions prior to 1.27.1, this will open your `settings.json` file. + +You can still open the `settings.json` file by using **Preferences: Open Settings (JSON)** command from the Command Palette (`kb(workbench.action.showCommands)`) or by changing the default settings editor with the `"workbench.settings.editor"` setting. + +Go to [User and Workspace settings](/docs/getstarted/settings.md) for more information on configuring VS Code settings. + +## Multi-version support + +You can configure the PowerShell extension to use any version of PowerShell installed on your machine by following [these instructions](https://docs.microsoft.com/powershell/scripting/core-powershell/vscode/using-vscode?view=powershell-6#using-a-specific-installed-version-of-powershell). + +You can also change the version by clicking on the version number in the lower right corner: + +![Change PowerShell Version](images/powershell/pwshChangeVersion.png) + +Or run the **PowerShell: Show Session Menu** command from the Command Palette (`kb(workbench.action.showCommands)`). + +## Pester + +[Pester](https://github.com/pester/Pester/wiki/Pester) is a [Behavior-driven Development](https://en.wikipedia.org/wiki/Behavior-driven_development) (BDD) based unit test runner for PowerShell. Pester provides a framework for running unit tests to execute and validate PowerShell commands. Pester follows a file naming convention for naming tests to be discovered by Pester at test time and a simple set of functions that expose a testing [domain-specific language](https://en.wikipedia.org/wiki/Domain-specific_language) (DSL) for isolating, running, evaluating and reporting the results of PowerShell commands. + +Windows 10 and Server 2016 comes with Pester 3.40 pre-installed. To update Pester or to install the latest version on other platforms follow the [Pester installation instructions](https://github.com/pester/Pester#installation). + +![Pester CodeLens Integration](images/powershell/pesterCodeLens.png) + +## Plaster + + Plaster is a template-based file and project generator written in PowerShell. Its purpose is to streamline the creation of PowerShell module projects, Pester tests, DSC configurations and more. See the [GitHub Plaster repository](https://github.com/PowerShell/Plaster) for more information, for documentation on Plaster's cmdlets see [Cmdlet Documentation](https://github.com/PowerShell/Plaster/blob/master/docs/en-US/Plaster.md). + +The PowerShell extension allows the creation of new Plaster projects by running the **PowerShell: Create New Project from Plaster Template** command from the Command Palette (`kb(workbench.action.showCommands)`). + +![Plaster Project](images/powershell/cpPlasterCommand.png) + +## PSScriptAnalyzer + +[PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer#introduction) is a static source code checker for PowerShell modules and scripts. PSScriptAnalyzer checks the quality of PowerShell code by running a set of rules. The rules are based on PowerShell best practices identified by the PowerShell Team and the community. Pester generates diagnostic records (errors and warnings) to inform users about potential code defects and suggests possible solutions for improvements. + +The PowerShell extension includes PSScriptAnalyzer by default, and automatically performs analysis on PowerShell script files being edited in VS Code. + +### PSScriptAnalyzer Settings + +PSScriptAnalyzer is shipped with a collection of built-in rules that checks various aspects of PowerShell source code such as presence of uninitialized variables, usage of PSCredential Type, usage of Invoke-Expression, etc. Additional functionality such as exclude/include specific rules is also supported. + +To disable PSScriptAnalyzer, open your settings, browse Extensions, select the PowerShell extension and deselect the checkbox for PSScriptAnalyzer. + +![PSScriptAnalyzer Settings](images/powershell/pssaExtensionSetting.png) + +Format document command is provided by the PSScriptAnalyzer module. + +### Document Formatting + +Automatic document formatting can be invoked using the **Format Document** command or the (`kb(editor.action.formatDocument)`) keyboard shortcut. + +## CodeLens + +CodeLenses are a VS Code feature to provide actionable, contextual information that is displayed within the source code. + +CodeLens support was added in version 1.3.0 of the PowerShell extension, read the [PowerShell extension changelog](https://marketplace.visualstudio.com/items/ms-vscode.PowerShell/changelog) for more information. + +### Pester CodeLens support + +Pester supports CodeLens integration for **Run tests** and **Debug tests**. + +### CodeLens Pester debug support + +![CodeLens Pester Debug Support](images/powershell/codeLensPesterDebug.gif) + +### CodeLens Pester symbol support + +![CodeLens Pester Symbol Support](images/powershell/codeLensPesterSymbol.gif) + +### Function reference CodeLens support + +CodeLens function reference support shows the number of times a function is referenced within your code and allows you to jump to specific references. + +![CodeLens Function Reference Support](images/powershell/codeLensFuncRef.gif) + +## Extension FAQ page + +Check out the FAQ page on the [PowerShell extensions Wiki](https://github.com/PowerShell/vscode-powershell/wiki/FAQ) + +## Types.ps1xml and Format.ps1xml files + +`ps1xml` files are PowerShell's way to extend the type system and define output formatting. For more information on these files, please refer to the official PowerShell documentation on [`Types.ps1xml`](https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_types.ps1xml?view=powershell-6) and [`Format.ps1xml`](https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_format.ps1xml?view=powershell-6). +You can get IntelliSense features when authoring `ps1xml` files by installing the [XML extension by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml). +After installing, add this configuration to your user settings: + +```json +"xml.fileAssociations": [ + { + "systemId": "https://raw.githubusercontent.com/PowerShell/PowerShell/master/src/Schemas/Format.xsd", + "pattern": "**/*.Format.ps1xml" + }, + { + "systemId": "https://raw.githubusercontent.com/PowerShell/PowerShell/master/src/Schemas/Types.xsd", + "pattern": "**/*.Types.ps1xml" + } +] +``` + +This tells the XML extension to use the official XML schemas from the PowerShell repository for all `.ps1xml` files. +This enables the following features in `ps1xml` files: + +- Syntax error reporting +- Schema validation +- Tag and attribute completion +- Auto-close tags +- Symbol highlighting +- Document folding +- Document symbols and outline +- Renaming support +- Document Formatting diff --git a/docs/languages/python.md b/docs/languages/python.md new file mode 100644 index 0000000000000000000000000000000000000000..a0e4989cf30675a9c1f8b849d836e123c8a65597 --- /dev/null +++ b/docs/languages/python.md @@ -0,0 +1,141 @@ +--- +Order: 11 +Area: languages +TOCTitle: Python +ContentId: c2cb770d-571d-4edf-9eb9-b5b8977c21a0 +PageTitle: Python in Visual Studio Code +DateApproved: 03/07/2019 +MetaDescription: Learn about Visual Studio Code as a Python IDE (code completion, debugging, snippets, linting). +--- +# Python in Visual Studio Code + +Working with Python in Visual Studio Code, using the [Microsoft Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python), is simple, fun, and productive. The extension makes VS Code an excellent IDE, and works on any operating system with a variety of Python interpreters. It leverages all of VS Code's power to provide auto complete and IntelliSense, linting, debugging, and unit testing, along with the ability to easily switch between Python environments, including virtual and conda environments. + +This article provides only an overview of the different capabilities of the Python extension for VS Code. For a walkthrough of editing, running, and debugging code, use the button below. + +Python Hello World Tutorial + +## Install Python and the Python extension + +The [tutorial](/docs/python/python-tutorial.md) guides you through installing Python and using the extension. You must install a Python interpreter yourself separately from the extension. For a quick install, use [Python 3.6 from python.org](https://www.python.org/downloads/) and [install the extension from the VS Code marketplace](https://marketplace.visualstudio.com/items?itemName=ms-python.python). + +Once you have a version of Python installed, activate it using the **Python: Select Interpreter** command. If VS Code doesn't automatically locate the interpreter you're looking for, refer to [Environments - Manually specify an interpreter](/docs/python/environments.md#manually-specify-an-interpreter). + +You configure the Python extension through settings. See the [Settings reference](/docs/python/settings-reference.md). + +## Run Python code + +To experience Python, create a file (using the [File Explorer](/docs/getstarted/userinterface.md#explorer)) named `hello.py` and paste in the following code (assuming Python 3): + +```python +print("Hello World") +``` + +The Python extension then provides shortcuts to run Python code in the currently selected interpreter (**Python: Select Interpreter** in the Command Palette): + +- In the text editor: right-click anywhere in the editor and select **Run Python File in Terminal**. If invoked on a selection, only that selection is run. +- In Explorer: right-click a Python file and select **Run Python File in Terminal**. + +You can also use the **Terminal: Create New Integrated Terminal** command to create a terminal in which VS Code automatically activates the currently selected interpreter. See [Environments](#environments) below. The **Python: Start REPL** activates a terminal with the currently selected interpreter and then runs the Python REPL. + +For a more specific walkthrough on running code, see the [tutorial](/docs/python/python-tutorial.md). + +## Autocomplete and IntelliSense + +The Python extension supports code completion and IntelliSense using the currently selected interpreter. [IntelliSense](/docs/editor/intellisense.md) is a general term for a number of features, including intelligent code completion (in-context method and variable suggestions) across all your files and for built-in and third-party modules. + +IntelliSense quickly shows methods, class members, and documentation as you type, and you can trigger completions at any time with `kb(editor.action.triggerSuggest)`. You can also hover over identifiers for more information about them. + +![IntelliSense and autocomplete for Python code](images/python/python-editing.gif) + +> **Tip**: Check out the [IntelliCode extension for VS Code (preview)](https://go.microsoft.com/fwlink/?linkid=2006060). IntelliCode provides a set of AI-assisted capabilities for IntelliSense in Python, such as inferring the most relevant auto-completions based on the current code context. + +## Linting + +Linting analyzes your Python code for potential errors, making it easy to navigate to and correct different problems. + +The Python extension can apply a number of different linters including Pylint, Pep8, Flake8, mypy, pydocstyle, prospector, and pylama. See [Linting](/docs/python/linting.md). + + + +## Debugging + +No more `print` statement debugging! Set breakpoints, inspect data, and use the debug console as you run your program step by step. Debug a number of different types of Python applications, including multi-threaded, web, and remote applications. + +For Python-specific details, including setting up your `launch.json` configuration and remote debugging, see [Debugging](/docs/python/debugging.md). General VS Code debugging information is found in the [debugging document](/docs/editor/debugging.md). The [Django](/docs/python/tutorial-django.md) and [Flask](/docs/python/tutorial-flask.md) tutorials also demonstrate debugging in the context of those web apps, including debugging Django page templates. + + + +## Snippets + +Snippets take productivity to the next level. You can configure [your own snippets](/docs/editor/userdefinedsnippets.md) and use snippets provided by an extension. Snippets appear in the same way as code completion `kb(editor.action.triggerSuggest)`. For specific examples with Python, see the [Django](/docs/python/tutorial-django.md) and [Flask](/docs/python/tutorial-flask.md) tutorials. + + + +## Environments + +The Python extension automatically detects Python interpreters that are installed in standard locations. It also detects conda environments as well as virtual environments in the workspace folder. See [Configuring Python environments](/docs/python/environments.md). You can also use the `python.pythonPath` setting to point to an interpreter anywhere on your computer. + +The current environment is shown on the left side of the VS Code Status Bar: + +![Selected Python interpreter in the Status Bar](images/python/selected-interpreter-status-bar.png) + +The Status Bar also indicates if no interpreter is selected: + +![Status bar showing no selected Python interpreter](images/python/no-interpreter-selected-statusbar.png) + +The selected environment is used for IntelliSense, auto-completions, linting, formatting, and any other language-related feature other than debugging. It is also activated when you use [run Python in a terminal](#run-python-in-the-terminal). + +To change the current interpreter, which includes switching to conda or virtual environments, select the interpreter name on the Status Bar or use the **Python: Select Interpreter** command. + +![Python: Select Interpreter command](images/python/select-interpreters-command.png) + +VS Code prompts you with a list of detected environments as well as any you've added manually to your user settings (see [Configuring Python environments](/docs/python/environments.md)). + +### Installing packages + +Packages are installed using the **Terminal** panel and commands like `pip install ` (Windows) and `pip3 install ` (macOS/Linux). VS Code installs that package into your project along with its dependencies. Examples are given in the [Python tutorial](/docs/python/python-tutorial.md#install-and-use-packages) as well as the [Django](/docs/python/tutorial-django.md) and [Flask](/docs/python/tutorial-flask.md) tutorials. + +## Jupyter notebooks + +If you open a [Jupyter notebook](http://jupyter.org/) file (`.ipynb`) in VS Code, the Python extension prompts you to import the notebook as a Python code file. The notebook's cells are delimited in the Python file with `#%%` comments, and the Python extension shows **Run Cell** or **Run All Cells** CodeLens. Selecting either CodeLens starts the Jupyter server and runs the cell(s) in the Python interactive window: + +![Jupyter notebook running in VS Code and the Python interactive window](images/python/jupyter.png) + +You can also connect to a remote Jupyter server for running the code. + +Furthermore, importing a notebook into VS Code allows you to use all of VS Code's debugging capabilities. You can then save the notebook file and open it again as a notebook in Jupyter or upload to a service like [Azure Notebooks](https://docs.microsoft.com/azure/notebooks). + +For more information, see [Jupyter support](/docs/python/jupyter-support.md). + +## Unit testing + +The Python extension supports [unit testing](/docs/python/unit-testing.md) with the unittest, pytest, and nose test frameworks. + +To run unit tests, you enable one of the frameworks in settings. Each framework also has specific settings, such as arguments that identify paths and patterns for test discovery. + +Once discovered, VS Code provides a variety of commands (on the Status Bar, the Command Palette, and elsewhere) to run and debug tests, including ability to run individual test files and individual methods. + +## Configuration + +The Python extension provides a wide variety of settings for its various features. These are described on their relevant topics, such as [Editing code](/docs/python/editing.md), [Linting](/docs/python/linting.md), [Debugging](/docs/python/debugging.md), and [Unit Testing](/docs/python/unit-testing.md). The complete list is found in the [Settings reference](/docs/python/settings-reference.md). + +## Other popular Python extensions + +The [Microsoft Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) provides all of the features described previously in this article. Additional Python language support can be added to VS Code by installing other popular Python extensions. For Jupyter support, we recommend the "Jupyter" extension from Don Jayamanne. + +1. Open the **Extensions** view (`kb(workbench.view.extensions)`). +1. Filter the extension list by typing 'python'. + +
+ +The extensions shown above are dynamically queried. Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com/vscode). + +## Next steps + +- [Python Hello World tutorial](/docs/python/python-tutorial.md) - Get started with Python in VS Code. +- [Editing Python](/docs/python/editing.md) - Learn about auto-completion, formatting, and refactoring for Python. +- [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +- [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +- [Django tutorial](/docs/python/tutorial-django.md) +- [Flask tutorial](/docs/python/tutorial-flask.md) diff --git a/docs/languages/tsql.md b/docs/languages/tsql.md new file mode 100644 index 0000000000000000000000000000000000000000..8802f739f88386b0bb67ba6cdbd8003fa2b7bf55 --- /dev/null +++ b/docs/languages/tsql.md @@ -0,0 +1,87 @@ +--- +Order: 14 +Area: languages +TOCTitle: T-SQL +ContentId: 5325cf50-e4c7-11e6-bf01-fe55135034f3 +PageTitle: Transact-SQL with Visual Studio Code +DateApproved: 1/24/2017 +MetaDescription: Learn about Visual Studio Code editor features (code completion, debugging, snippets, linting) for Transact-SQL. +--- +# Transact-SQL in Visual Studio Code + +Turn Visual Studio Code into a powerful editor for [Transact-SQL] (T-SQL) development with the [mssql] extension available in the VS Code Marketplace. The [mssql] extension is optimized to work with SQL Server running on-premises, in any cloud, Azure SQL Database, and Azure SQL Data Warehouse. + +Connect to SQL databases, type T-SQL code, execute T-SQL code, view results, and save results as JSON or CSV files. While typing T-SQL code, you get rich T-SQL language features like T-SQL IntelliSense (code completion), syntax highlighting, linting, code navigation and code snippets. + +> [Download VS Code] - If you haven't downloaded VS Code yet, quickly install for your platform (Linux, macOS or Windows). + +## Install T-SQL support + +Add T-SQL language support to VS Code by installing the [mssql] extension from the VS Code marketplace as follows: + +1. Open the **Extensions** view from VS Code Side Bar (`kb(workbench.view.extensions)`). +2. Type "mssql" in the search bar, click **Install**, and reload VS Code when prompted. + +![install mssql extension](images/tsql/install-mssql.png) + +## Connect and Execute T-SQL + +Easily connect to SQL Server running on-premises, in any cloud, Azure SQL Database, and Azure SQL Data Warehouse. Then, execute your T-SQL statements and batches to view results and messages - all within VS Code. Your recent connections are saved across sessions so you can quickly connect to your databases again. + +![execute tsql](images/tsql/execute.gif) + +## View and Save Results + +View results and messages when you execute your T-SQL code. Save results as a JSON or CSV file to use the data in your applications with just a few clicks. + +![save tsql](images/tsql/save.gif) + +## T-SQL IntelliSense + +As you type T-SQL code in the editor, VS Code provides intelligent code completion for T-SQL keywords, suggestions for schema object names (tables, columns, views), and parameter help for functions and procedures when connected to a database. + +![tsql intellisense](images/tsql/intellisense.gif) + +## Linting + +Linting is the analysis of your T-SQL code for potential syntax errors. Use Visual Studio Code to quickly navigate to the errors and warnings in your T-SQL code as you type. + +![tsql linting](images/tsql/linting.gif) + +## Peek Definition/Go to Definition + +Use **Peek Definition** and **Go to Definition** to quickly browse the definition of schema objects in your database such as tables, functions, and procedures while typing T-SQL code. + +![tsql peek definition](images/tsql/peekdefinition.gif) + +## Snippets + +T-SQL snippets provide code templates for commonly used T-SQL statements. Type "sql" to get the list of T-SQL snippets. + +![tsql snippets](images/tsql/snippets.gif) + +## Next steps + +* Download the free [SQL Server 2017 Developer Edition]. +* Install the [mssql] extension from the Visual Studio Code Marketplace. +* [Build an app] using SQL Server - Get started with SQL Server on macOS, Linux, and Windows using your favorite programming language. +* Contribute to the mssql extension on [GitHub]. Submit a bug report or a feature suggestion on our [GitHub Issue Tracker]. + +## Further Reading + +* [SQL Server documentation] +* [SQL Server on Linux documentation] +* [SQL Server Blog] +* [SQL Server Videos] on Channel9 + +[Transact-SQL]: https://docs.microsoft.com/sql/t-sql/language-reference +[mssql]: https://aka.ms/mssql-marketplace +[Download VS Code]: https://code.visualstudio.com/download +[SQL Server 2017 Developer Edition]: https://www.microsoft.com/sql-server/sql-server-downloads +[Build an app]: https://aka.ms/sqldev +[SQL Server documentation]: https://docs.microsoft.com/sql/sql-server/sql-server-technical-documentation +[SQL Server on Linux documentation]: https://docs.microsoft.com/sql/linux/ +[SQL Server Blog]: https://blogs.technet.microsoft.com/dataplatforminsider/ +[SQL Server Videos]: https://channel9.msdn.com/Tags/sql+server +[GitHub]: https://github.com/Microsoft/vscode-mssql +[GitHub Issue Tracker]: https://github.com/Microsoft/vscode-mssql/issues diff --git a/docs/languages/typescript.md b/docs/languages/typescript.md new file mode 100644 index 0000000000000000000000000000000000000000..336c9118fd64914b4acadca78faad6fcfbad7ba0 --- /dev/null +++ b/docs/languages/typescript.md @@ -0,0 +1,290 @@ +--- +Order: 6 +Area: languages +TOCTitle: TypeScript +ContentId: 05C114DF-4FDC-4C65-8954-58F5F293FAFD +PageTitle: TypeScript Programming with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Get the best out editing TypeScript with Visual Studio Code. +MetaSocialImage: images/typescript/Languages_typescript.png +--- + +# TypeScript in Visual Studio Code + +[TypeScript](https://www.typescriptlang.org) is a typed superset of JavaScript that compiles to plain JavaScript. It offers classes, modules, and interfaces to help you build robust components. The TypeScript language specification can be found [here](https://github.com/Microsoft/TypeScript/tree/master/doc). + +![Working with TypeScript in Visual Studio Code](images/typescript/overview.png) + +## Installing the TypeScript compiler + +Visual Studio Code includes TypeScript language support but does not include the TypeScript compiler, `tsc`. You will need to install the TypeScript compiler either globally or in your workspace to transpile TypeScript source code to JavaScript (`tsc HelloWorld.ts`). + +The easiest way to install TypeScript is through npm, the [Node.js Package Manager](https://www.npmjs.com/). If you have npm installed, you can install TypeScript globally (`-g`) on your computer by: + +```bash +npm install -g typescript +``` + +You can test your install by checking the version. + +```bash +tsc --version +``` + +Another option is to install the TypeScript compiler locally in your project (`npm install --save-dev typescript`) and has the benefit of avoiding possible interactions with other TypeScript projects you may have. + +## IntelliSense + +IntelliSense shows you intelligent code completion, hover info, and signature information so that you can write code more quickly and correctly. + + + +VS Code provides IntelliSense for individual TypeScript files as well as TypeScript `tsconfig.json` projects. + +## Snippets + +VS Code includes basic TypeScript [snippets](/docs/editor/userdefinedsnippets.md) that are suggested as you type; + + + +You can install extensions to get additional snippets or define your own snippets for TypeScript. See [User Defined Snippets](/docs/editor/userdefinedsnippets.md) for more information. + +> **Tip**: You can disable snippets by setting `editor.snippetSuggestions` to `"none"` in your [settings](/docs/getstarted/settings.md) file. If you'd like to see snippets, you can specify the order relative to suggestions; at the top (`"top"`), at the bottom (`"bottom"`), or inlined ordered alphabetically (`"inline"`). The default is `"inline"`. + +## JSDoc support + +VS Code's TypeScript IntelliSense understands many standard [JSDoc](http://usejsdoc.org) annotations, and uses them to show typing information and documentation in [suggestions](#intellisense), [hover info](#hover-information), and [signature help](#signature-help). + +![TypeScript language within VS Code](images/typescript/jsdocs.png) + +Keep in mind that when using JS Doc for TypeScript code, you should not include type annotations. The TypeScript compiler only uses TypeScript type annotations and ignores those from JS Doc. + + + +To disable JSDoc comment suggestions in TypeScript, set `"typescript.suggest.completeJSDocs": false`. + +## Hover information + +Hover over a TypeScript symbol to quickly see its type information and relevant documentation: + +![Hover for a lodash function](images/typescript/hover.png) + +You can also show the hover info at the current cursor position with the `kb(editor.action.showHover)` keyboard shortcut. + +## Signature help + +As you write a TypeScript function call, VS Code shows information about the function signature and highlights the parameter that you are currently completing: + +![Signature help for the lodash capitalize function](images/typescript/signature-help.png) + +Signature help is shown automatically when you type a `(` or `,` within a function call. Use `kb(editor.action.triggerParameterHints)` to manually trigger signature help. + +## Auto imports + +Automatic imports speed up coding by helping you find available symbols and automatically adding imports for them. + +Just start typing to see [suggestions](#intellisense) for all available TypeScript symbols in your current project. + +![Global symbols are shown in the suggestion list](images/typescript/auto-import-pre.png) + +If you choose one of the suggestions from another file or module, VS Code will automatically add an import for it. In this example, VS Code adds an import for `Hercules` to the top of the file: + +![After selecting a symbol from a different file, an import is added for it automatically](images/typescript/auto-import-post.png) + +You can disable auto imports by setting `"typescript.autoImportSuggestions.enabled": false`. + +## Formatting + +VS Code includes a TypeScript formatter that providers basic code formatting with reasonable defaults. + +Use the `typescript.format.*` [settings](/docs/getstarted/settings.md) to configure the built-in formatter, such as making braces appear on their own line. Or, if the built-in formatter is getting in the way, set `"typescript.format.enable"` to `false` to disable it. + +For more specialized code formatting styles, try installing one of the formatting extensions from the VS Code marketplace. + +## JSX and auto closing tags + +VS Code's TypeScript features also work with [JSX](https://reactjs.org/docs/introducing-jsx.html). To use JSX in your TypeScript, use the `*.tsx` file extension instead of the normal `*.ts`: + +![IntelliSense in JSX](images/typescript/jsx.png) + +VS Code also includes JSX-specific features such as autoclosing of JSX tags in TypeScript: + + + +Set `"typescript.autoClosingTags"` to `false` to disable JSX tag closing. + +## Code navigation + +Code navigation lets you quickly navigate TypeScript projects. + +- **Go To Definition** `kb(editor.action.revealDefinition)` - Go to the source code of a symbol definition. +- **Peek Definition** `kb(editor.action.peekDefinition)` - Bring up a Peek window that shows the definition of a symbol. +- **Peek References** `kb(editor.action.referenceSearch.trigger)` - Show all references to a symbol. +- **Go to Type Definition** `kb(editor.action.goToTypeDefinition)` - Go to the type that defines a symbol. For an instance of a class, this will reveal the class itself instead of where the instance is defined. +- **Go to Implementation** `kb(editor.action.goToImplementation)` - Go to the implementations of an interface or abstract method. + +You can navigate via symbol search using the **Go to Symbol** commands from the **Command Palette** (`kb(workbench.action.showCommands)`). + +- **Go to Symbol in File** `kb(workbench.action.gotoSymbol)` +- **Go to Symbol in Workspace** `kb(workbench.action.showAllSymbols)` + +## Rename + +Press `kb(editor.action.rename)` to rename the symbol under the cursor across your TypeScript project: + +![Renaming a method](images/typescript/rename.png) + +## Refactoring + +VS Code includes some handy refactorings for TypeScript such as **Extract function** and **Extract constant**. Just select the source code you'd like to extract and then click on the lightbulb in the gutter or press (`kb(editor.action.quickFix)`) to see available refactorings. + +![TypeScript refactoring](images/typescript/refactorings.png) + +Available refactorings include: + +- Extract to method or function. +- Extract to constant. +- Convert between named imports and namespace imports. +- Move to new file. + +See [Refactorings](/docs/editor/refactoring.md) for more information about refactorings and how you can configure keyboard shortcuts for individual refactorings. + +## Quick fixes + +Quick fixes are suggested edits that address simple coding errors. Example quick fixes include: + +- Adding a missing `this` to a member access. +- Fixing a misspelled property name. +- Removing unreachable code or unused imports +- Declaring + +When you move your cursor on to a TypeScript error, VS Code shows a lightbulb that indicates that quick fixes are available. Click the lightbulb or press `kb(editor.action.quickFix)` to show a list of available quick fixes and [refactorings](#refactoring). + +## Unused variables and unreachable code + +Unused TypeScript code, such the else block of an `if` statement that is always true or an unreferenced import, is faded out in the editor: + +![Unreachable source code faded out](images/typescript/unreachable.png) + +You can quickly remove this unused code by placing the cursor on it and triggering the quick fix command (`kb(editor.action.quickFix)`) or clicking on the lightbulb. + +To disable fading out of unused code, set `"editor.showUnused"` to `false`. You can also disable fading of unused code only in TypeScriptScript by setting: + +```json +"[typescript]": { + "editor.showUnused": false +}, +"[typescriptreact]": { + "editor.showUnused": false +}, +``` + +## Organize Imports + +The **Organize Imports** source code action sorts the imports in a TypeScript file and removes and unused imports: + + + +You can run **Organize Imports** from the **Source Action** context menu or with the `kb(editor.action.organizeImports)` keyboard shortcut. + +Organize imports can also be automatically when you save a TypeScript file by setting: + +```json +"editor.codeActionsOnSave": { + "source.organizeImports": true +} +``` + +## Code suggestions + +VS Code automatically suggests some common code simplifications such as converting a chain of `.then` calls on a promise to use `async` and `await` + + + +Set `"typescript.suggestionActions.enabled"` to `false` to disable suggestions. + +## References CodeLens + +The TypeScript references CodeLens displays an inline count of reference for classes, interfaces, methods, properties, and exported objects: + +![TypeScript references CodeLens](images/typescript/ts-references-code-lens.png) + +You can enable this by setting `"typescript.referencesCodeLens.enabled": true` in the User Settings file. + +Click on the reference count to quickly browse a list of references: + +![TypeScript references CodeLens peek](images/typescript/ts-references-code-lens-peek.png) + +## Implementations CodeLens + +The TypeScript implementations CodeLens displays the number of implementors of an interface: + +![TypeScript implementations CodeLens](images/typescript/ts-implementations-code-lens.png) + +You can enable this by setting `"typescript.implementationsCodeLens.enabled": true`. + +As with the references CodeLens, you can click on the implementation count to quickly browse a list of all implementations. + +## Update imports on file move + +When you move or rename a file that is imported by other files in your TypeScript project, VS Code can automatically update all import paths that reference the moved file. + +The `typescript.updateImportsOnFileMove.enabled` setting controls this behavior. Valid settings values are: + +* `"prompt"` - The default. Asks if paths should be updated for each file move. +* `"always"` - Always automatically update paths. +* `"never"` - Do not update paths automatically and do not prompt. + +## Debugging + +VS Code comes with great debugging support for TypeScript, including support for sourcemaps. Set breakpoints, inspect objects, navigate the call stack, and execute code in the Debug Console. See more about debugging [here](/docs/editor/debugging.md). + +### Debug client side + +You can debug your client-side code using a browser debugger such as [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome), [Debugger for Edge](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-edge) or [Debugger for Firefox](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-firefox-debug). + +### Debug server side + +Debug Node.js in VS Code using the built-in debugger. Setup is easy and you can read a tutorial for Node.js debugging [here](/docs/nodejs/nodejs-tutorial.md#debugging-your-express-application). + +![debug data inspection](images/javascript/debug_data_inspection.gif) + +## Linters + +[Linters](https://en.wikipedia.org/wiki/Lint_%28software%29) provides warnings for suspicious looking code. While VS Code does not include a built-in TypeScript linter, TypeScript linter [extensions](/docs/editor/extension-gallery.md) available in the marketplace. + +[TSLint](https://github.com/palantir/tslint) is a popular TypeScript linter. The [TSLint extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-typescript-tslint-plugin) integrates TSLint into VS Code so you can see linting errors right in the editor and even quickly many of fix them with [quick fixes](#quick-fixes). + +## TypeScript extensions + +VS Code provides many features for TypeScript out of the box. In addition to what comes built-in, you can install an extension for greater functionality. + +
+ +> Tip: Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com). + +## Next steps + +To learn more, see: + +* [TypeScript tutorial](/docs/typescript/typescript-tutorial.md) - Create a simple Hello World TypeScript in VS Code. +* [Compiling TypeScript](/docs/typescript/typescript-compiling.md) - Compile TypeScript to a JavaScript target version. +* [Debugging TypeScript](/docs/typescript/typescript-debugging.md) - Learn about debugging TypeScript both server and client-side with VS Code. + +## Common questions + +### Can I use the version of TypeScript that ships with VS 2015? + +No, the TypeScript language service which ships with Visual Studio 2015 and 2017 isn't compatible with VS Code. You will need to install a separate version of TypeScript from [npm](https://www.npmjs.com/package/typescript). diff --git a/docs/nodejs/angular-tutorial.md b/docs/nodejs/angular-tutorial.md new file mode 100644 index 0000000000000000000000000000000000000000..15ef7e6e5eb184a3a5a3cbfa389275889f070bb4 --- /dev/null +++ b/docs/nodejs/angular-tutorial.md @@ -0,0 +1,185 @@ +--- +Order: 6 +Area: nodejs +TOCTitle: Angular Tutorial +ContentId: f6b7b0c2-ccbe-4e5f-8f2e-6c1ecea52f69 +PageTitle: Angular JavaScript Tutorial in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Angular JavaScript tutorial showing IntelliSense, debugging, and code navigation support in the Visual Studio Code editor. +MetaSocialImage: images/angular/Welcome-to-app.png +--- +# Using Angular in Visual Studio Code + +[Angular](https://angular.io/) is a popular JavaScript library for building web application user interfaces developed by Google. The Visual Studio Code editor supports Angular IntelliSense and code navigation out of the box. + +![Welcome to app](images/angular/Welcome-to-app.png) + +## Welcome to Angular + +We'll be using the [Angular CLI](https://cli.angular.io/) for this tutorial. To install and use the command line interface as well as run the Angular application server, you'll need the [Node.js](https://nodejs.org/) JavaScript runtime and [npm](https://www.npmjs.com/) (the Node.js package manager) installed. npm is included with Node.js which you can install from [here](https://nodejs.org/en/download/). + +>**Tip**: To test that you have Node.js and npm correctly installed on your machine, you can type `node --version` and `npm --version`. + +To install the Angular CLI, in a terminal or command prompt type: + +```bash +npm install -g @angular/cli +``` + +This may take a few minutes to install. You can now create a new Angular application by typing: + +```bash +ng new my-app +``` + +`my-app` is the name of the folder for your application. This may take a few minutes to create the Angular application in [TypeScript](/docs/languages/typescript.md) and install its dependencies. + +Let's quickly run our Angular application by navigating to the new folder and typing `ng serve` to start the web server and open the application in a browser: + +```bash +cd my-app +ng serve +``` + +You should see "Welcome to app!!" on [http://localhost:4200](http://localhost:4200) in your browser. We'll leave the web server running while we look at the application with VS Code. + +To open your Angular application in VS Code, open another terminal (or command prompt) and navigate to the `my-app` folder and type `code .`: + +```bash +cd my-app +code . +``` + +### Syntax highlighting and bracket matching + +Now expand the `src\app` folder and select the `app.component.ts` file. You'll notice that VS Code has syntax highlighting for the various source code elements and, if you put the cursor on a parentheses, the matching bracket is also selected. + +![angular bracket matching](images/angular/bracket-matching.png) + +### IntelliSense + +As you hover your mouse over text in the file, you'll see that VS Code gives you information about key items in your source code. Items such as variables, classes and Angular decorators are a few examples where you'll be presented with this information. + +![angular decorator hover](images/angular/decorator-hover.png) + +As you start typing in `app.component.ts`, you'll see smart suggestions and code snippets. + +![angular suggestions](images/angular/suggestions.png) + +You can click the information button (`i`) to see a flyout with more documentation. + +![angular intellisense](images/angular/intellisense.png) + +VS Code uses the TypeScript language service for code intelligence ([IntelliSense](/docs/editor/intellisense.md)) and it has a feature called [Automatic Type Acquisition](/docs/languages/javascript.md#automatic-type-acquisition) (ATA). ATA pulls down the npm Type Declaration files (`*.d.ts`) for the npm modules referenced in the `package.json`. + +### Go to Definition, Peek definition + +Through the TypeScript language service, VS Code can also provide type definition information in the editor through **Go to Definition** (`kb(editor.action.revealDefinition)`) or **Peek Definition** (`kb(editor.action.peekDefinition)`). Open the `app.module.ts` file and put the cursor over `AppComponent` in the `bootstrap` property declaration, right click and select **Peek Definition**. A [Peek window](/docs/editor/editingevolved.md#peek) will open showing the `AppComponent` definition from `app.component.ts`. + +![angular peek definition](images/angular/peek-definition.png) + +Press `kbstyle(Escape)` to close the Peek window. + +## Hello World! + +Let's update the sample application to "Hello World". Go back to the `app.component.ts` file and change the `title` string in `AppComponent` to "Hello World". + +```ts +import { Component } from '@angular/core'; + +@Component({ + selector: 'app-root', + templateUrl: './app.component.html', + styleUrls: ['./app.component.css'] +}) +export class AppComponent { + title = 'Hello World'; +} +``` + +Once you save the `app.component.ts` file, the running instance of the server will update the web page and you'll see "Welcome to Hello World!!". + +>**Tip**: VS Code supports Auto Save, which by default saves your files after a delay. Check the **Auto Save** option in the **File** menu to turn on Auto Save or directly configure the `files.autoSave` user [setting](/docs/getstarted/settings.md). + +![hello world](images/angular/hello-world.png) + +## Debugging Angular + +To debug the client side Angular code, we'll need to install the [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) extension. + +>Note: This tutorial assumes you have the Chrome browser installed. Microsoft also publishes a version of this extension for their [Edge](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-edge) browser. + +Open the Extensions view (`kb(workbench.view.extensions)`) and type 'chrome` in the search box. You'll see several extensions which reference Chrome. + +![debugger for chrome](images/reactjs/debugger-for-chrome.png) + +Press the **Install** button for **Debugger for Chrome**. The button will change to **Installing** then, after completing the installation, it will change to **Reload**. Press **Reload** to restart VS Code and activate the extension. + +### Set a breakpoint + +To set a breakpoint in `app.component.ts`, click on the gutter to the left of the line numbers. This will set a breakpoint which will be visible as a red circle. + +![set a breakpoint](images/angular/breakpoint.png) + +### Configure the Chrome debugger + +We need to initially configure the [debugger](/docs/editor/debugging.md). To do so, go to the Debug view (`kb(workbench.view.debug)`) and click on the gear button to create a `launch.json` debugger configuration file. Choose **Chrome** from the **Select Environment** drop-down list. This will create a `launch.json` file in a new `.vscode` folder in your project which includes a configuration to launch the website. + +We need to make one change for our example: change the port of the `url` from `8080` to `4200`. Your `launch.json` should look like this: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "chrome", + "request": "launch", + "name": "Launch Chrome against localhost", + "url": "http://localhost:4200", + "webRoot": "${workspaceFolder}" + } + ] +} +``` + +Press `kb(workbench.action.debug.start)` or the green arrow to launch the debugger and open a new browser instance. The source code where the breakpoint is set runs on startup before the debugger was attached so we won't hit the breakpoint until we refresh the web page. Refresh the page and you should hit your breakpoint. + +![hit breakpoint](images/angular/hit-breakpoint.png) + +You can step through your source code (`kb(workbench.action.debug.stepOver)`), inspect variables such as `AppComponent`, and see the call stack of the client side Angular application. + +![debug variable](images/angular/debug-variable.png) + +The **Debugger for Chrome** extension README has lots of information on other configurations, working with sourcemaps, and troubleshooting. You can review it directly within VS Code from the **Extensions** view by clicking on the extension item and opening the **Details** view. + +![debugger for chrome readme](images/reactjs/chrome-debugger-readme.png) + +## Popular Starter Kits + +In this tutorial, we used the Angular CLI to create a simple Angular application. There are lots of great samples and starter kits available to help build your first Angular application. + +### Recipes + +The VS Code team has created [recipes](https://github.com/Microsoft/vscode-recipes) for more complex debugging scenarios. There you'll find the [Chrome Debugging with Angular CLI](https://github.com/Microsoft/vscode-recipes/tree/master/Angular-CLI) recipe which also uses the Angular CLI and goes into detail on debugging the generated project's unit tests. + +### MEAN Starter + +If you'd like to see a full MEAN (MongoDB, Express, Angular, Node.js) stack example, look at [MEAN.IO](http://mean.io/). They have documentation and an application generator for a sample MEAN project. You'll need to install and start [MongoDB](https://docs.mongodb.com/v3.0/installation/), but you'll quickly have a MEAN application running. VS Code also has great [MongoDB support](/docs/azure/mongodb.md) through the [Azure Cosmos DB](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb) extension. + +### React + +[React](https://facebook.github.io/react/) is another popular web framework. If you'd like to see an example of React working with VS Code, check out the [Using React in VS Code](/docs/nodejs/reactjs-tutorial.md) tutorial. It will walk you through creating an React application and configuring the `launch.json` file for the [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) extension. + +## Angular Extensions + +In addition to the functionality VS Code provides out of the box, you can install VS Code extensions for greater functionality. + +
+ +Click on an extension tile above to read the description and reviews on the [Marketplace](https://marketplace.visualstudio.com). + +To find other Angular extensions, open the Extensions view (`kb(workbench.view.extensions)`) and type 'angular' to see a filtered list of Angular extensions. + +![angular extensions](images/angular/angular-extensions.png) + +The community has also created "Extension Packs" which bundle useful extensions together (for example, a linter, debugger, and snippets) into a single download. To see available Angular extension packs, add the "extension packs" category to your filter (angular @category:"extension packs"). diff --git a/docs/nodejs/debugging-recipes.md b/docs/nodejs/debugging-recipes.md new file mode 100644 index 0000000000000000000000000000000000000000..cecc4e70a0856e116bd27d758ac017ffd4904c8d --- /dev/null +++ b/docs/nodejs/debugging-recipes.md @@ -0,0 +1,84 @@ +--- +Order: 9 +Area: nodejs +TOCTitle: Debugging Recipes +ContentId: 215832f9-d5bd-4cea-8cea-bfc4dc7ff7d1 +PageTitle: Node.js Debugging Recipes for Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Learn more about how to setup debugging in Visual Studio Code with debugging recipes +MetaSocialImage: debugging_Debugging.png +--- +# Node.js Debugging Recipes + +Visual Studio Code supports debugging of many languages and platforms via debuggers that are either built-in or contributed by extensions. + +To make it easier to get started with debugging, we have made a collection of debugging "recipes" which contain the steps and configuration you need to set up debugging for your favorite platform. The recipes are in GitHub at [https://github.com/Microsoft/vscode-recipes](https://github.com/Microsoft/vscode-recipes). + +## Debug server-side JavaScript in Node.js + +The Visual Studio Code editor supports debugging Node.js applications via the built-in [Node.js](https://nodejs.org/) debugger. + +![Node.js logo](images/recipes/nodejs.png) + +**Recipes:** + +- [Debugging Node.js with Nodemon](https://github.com/Microsoft/vscode-recipes/tree/master/nodemon) + +## Debug client-side JavaScript in Google Chrome + +The Visual Studio Code editor supports debugging of JavaScript running in [Google Chrome](https://electron.atom.io) applications via the [Debugger for Chrome extension](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome). + +![JavaScript and Chrome logo](images/recipes/chrome.png) + +You can read more about how our Debugger for Chrome works in this introduction [blog post](https://code.visualstudio.com/blogs/2016/02/23/introducing-chrome-debugger-for-vs-code). + +**Recipes:** + +- [Debugging Angular apps with Angular CLI](https://github.com/Microsoft/vscode-recipes/tree/master/Angular-CLI) +- [Debugging Next.js apps](https://github.com/Microsoft/vscode-recipes/tree/master/Next-js) +- [Debugging Meteor apps](https://github.com/Microsoft/vscode-recipes/tree/master/meteor) +- [Debugging Vue.js apps](https://github.com/Microsoft/vscode-recipes/tree/master/vuejs-cli) +- [Debugging Mocha tests](https://github.com/Microsoft/vscode-recipes/tree/master/debugging-mocha-tests) +- [Debugging Jest tests](https://github.com/Microsoft/vscode-recipes/tree/master/debugging-jest-tests) + +**Blog posts**: + +* [Live edit and debug your React apps directly from VS Code](https://medium.com/@auchenberg/live-edit-and-debug-your-react-apps-directly-from-vs-code-without-leaving-the-editor-3da489ed905f) + +* [Super-charged live editing and JavaScript debugging for Angular using VS Code](https://medium.com/@auchenberg/super-charged-live-editing-and-javascript-debugging-for-angular-using-visual-studio-code-c29da251ec71) + +## Debug Node.js in Docker containers + +This recipe shows how to run and debug a VS Code Node.js project written in TypeScript running inside a [Docker](https://www.docker.com) container. + +![Node.js TypeScript and Docker logos](images/recipes/node-typescript-docker.png) + +**Recipes:** + +- [Debugging Node.js with TypeScript in Docker](https://github.com/Microsoft/vscode-recipes/tree/master/Docker-TypeScript) + +## MERN - Mongo, Express, React and Node.js + +This recipe shows how to run and debug a MERN (Mongo, Express, React and Node.js) based project in VS Code. + +![MERN logos](images/recipes/mern.png) + +**Recipes:** + +- [Developing the MERN Starter in VS Code](https://github.com/Microsoft/vscode-recipes/tree/master/MERN-Starter) + +## Electron - Debug Electron applications + +The Visual Studio Code editor supports debugging [Electron](https://electron.atom.io) applications via the built-in [Node.js](https://nodejs.org/) debugger and the [Debugger for Chrome extension](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome). + +![electron logo](images/recipes/electron.png) + +**Recipes:** + +- [Debugging Electron Main and Renderer processes](https://github.com/Microsoft/vscode-recipes/tree/master/Electron) + +## Next steps + +* [Debugging](/docs/editor/debugging.md) - Read about general VS Code debugging features. +* [Node.js Debugging](/docs/nodejs/nodejs-debugging.md) - Learn about the built-in Node.js debugger. +* [Video: Getting started with Node.js debugging](https://www.youtube.com/watch?v=2oFKNL7vYV8) - Attach to a running Node.js process. diff --git a/docs/nodejs/emberjs-tutorial.md b/docs/nodejs/emberjs-tutorial.md new file mode 100644 index 0000000000000000000000000000000000000000..17bb01956416a1fee0d0ecc80674a0eea1acdd51 --- /dev/null +++ b/docs/nodejs/emberjs-tutorial.md @@ -0,0 +1,94 @@ +--- +Order: 8 +Area: nodejs +TOCTitle: Ember Tutorial +ContentId: 4a60ed36-93ff-4ff3-b650-ce74baa405ca +PageTitle: Ember JavaScript Tutorial in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Ember JavaScript tutorial showing IntelliSense and code navigation support in the Visual Studio Code editor. +--- +# Using Ember in Visual Studio Code + +[Ember](https://emberjs.com/) is a popular JavaScript framework for building web application user interfaces. The Visual Studio Code editor supports Ember.js IntelliSense and code navigation out of the box. + +![Welcome to app](images/emberjs/tomster-logo.png) + +## Welcome to Ember + +We'll be using the [Ember CLI](https://ember-cli.com/) for this tutorial. To install and use the command line interface as well as run the Ember.js application server, you'll need the [Node.js](https://nodejs.org/) JavaScript runtime and [npm](https://www.npmjs.com/) (the Node.js package manager) installed. npm is included with Node.js which you can install from [here](https://nodejs.org/en/download/). + +>**Tip**: To test that you have Node.js and npm correctly installed on your machine, you can type `node --version` and `npm --version`. + +To install Ember CLI, in a terminal or command prompt type: + +```bash +npm install -g ember-cli +``` + +This may take a few minutes to install. You can now create a new Ember.js application by typing: + +```bash +ember new my-app +``` + +`my-app` is the name of the folder for your application. This may take a few minutes to create the Ember application in [JavaScript](/docs/languages/javascript.md) and install its dependencies. + +Let's quickly run our Ember application by navigating to the new folder and typing `ember serve` to start the web server and open the application in a browser: + +```bash +cd my-app +ember serve +``` + +Once you see the **Build successful** message, you can open your browser to [http://localhost:4200](http://localhost:4200) and you should see "Congratulations, you made it!". You can press `kbstyle(Ctrl+C)` to stop the Ember server. + +![Ember welcome page](images/emberjs/welcome-page.png) + +To open your Ember application in VS Code, open another terminal (or command prompt) and navigate to the `my-app` folder and type `code .`: + +```bash +cd my-app +code . +``` + +### Syntax highlighting and bracket matching + +Now expand the `app` folder and select the `app.js` file. You'll notice that VS Code has syntax highlighting for the various source code elements and, if you put the cursor on a parentheses, the matching bracket is also selected. + +![react bracket matching](images/emberjs/bracket-matching.png) + +## IntelliSense + +As you start typing in `app.js`, you'll see smart suggestions or completions. + +![Ember suggestions](images/emberjs/suggestions.png) + +After you select a suggestion and type `.`, you see the types and methods on the object through [IntelliSense](/docs/editor/intellisense.md). + +![Ember intellisense](images/emberjs/intellisense.png) + +VS Code uses the TypeScript language service for its JavaScript code intelligence and it has a feature called [Automatic Type Acquisition](/docs/languages/javascript.md#automatic-type-acquisition) (ATA). ATA pulls down the npm Type Declaration files (`*.d.ts`) for the npm modules referenced in the `package.json`. + +If you select a method, you'll also get parameter help: + +![Ember parameter help](images/emberjs/parameter-help.png) + +### Go to Definition, Peek definition + +Through the TypeScript language service, VS Code can also provide type definition information in the editor through **Go to Definition** (`kb(editor.action.revealDefinition)`) or **Peek Definition** (`kb(editor.action.peekDefinition)`). Put the cursor over `Application`, right click and select **Peek Definition**. A [Peek window](/docs/editor/editingevolved.md#peek) will open showing the `Application` definition from `ember_application` Type Declaration file. + +![react peek definition](images/emberjs/peek-definition.png) + +Press `kbstyle(Escape)` to close the Peek window. + +## Extensions + +The VS Code Marketplace has many community created extensions for Ember.js development which add features like code snippets and advanced code suggestions. You can search in the Extensions view (`kb(workbench.view.extensions)`) by typing 'ember'. + +![Ember.js extensions](images/emberjs/ember-extensions.png) + +## Common questions + +### Can I debug Ember client side code with VS Code? + +You can use the [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) extension for client side debugging. Unfortunately it is difficult to get the configuration correct due to the sourcemaps created by the Ember CLI default transpiler. See [here](https://github.com/Microsoft/vscode-chrome-debug/issues/193) for an explanation and partial workaround. \ No newline at end of file diff --git a/docs/nodejs/extensions.md b/docs/nodejs/extensions.md new file mode 100644 index 0000000000000000000000000000000000000000..99d27f7282b8cbc0c0a4ce70fe4f70a85b8f5f25 --- /dev/null +++ b/docs/nodejs/extensions.md @@ -0,0 +1,89 @@ +--- +Order: 10 +Area: nodejs +TOCTitle: Extensions +ContentId: 3224f624-a3fc-4eeb-81d1-eb653a90a6fc +PageTitle: JavaScript Extensions in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Learn more about installing and integrating JavaScript and Node.js extensions in the Visual Studio Code editor. +MetaSocialImage: /assets/images/nodejs_javascript_vscode.png +--- +# JavaScript extensions for VS Code + +Visual Studio Code supports many features for JavaScript and Node.js development. The features that ship with the downloaded product are the core features: debugging, IntelliSense, code navigation, etc. + +In addition, to these core features, you can install a large number of quality extensions to add features to VS Code for JavaScript development. + +> **Tip:** To see how to install and manage your extensions, please refer to the [extension documentation](/docs/editor/extension-gallery.md). + +## Finding extensions + +You can find JavaScript extensions by typing `JavaScript` in the Extension view search bar. Alternatively, you can find JavaScript extensions using tags: "tag:javascript". Search for more extensions in VS Code or in the [Marketplace](https://marketplace.visualstudio.com/vscode). + +
+ +In addition you can search for `Node.js` extensions. + +
+ +> Tip: The extensions shown above are dynamically queried. Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com/vscode). + +## Recommended extensions + +If you are just getting started, here are the extensions we recommend trying out. + +### ESLint + +Marketplace - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) + +Publisher - [Dirk Baeumer](https://marketplace.visualstudio.com/search?term=publisher%3A%22Dirk%20Baeumer%22&target=VSCode) + +Easily integrate [ESLint](https://eslint.org/) into your project. If ESLint isn't your favorite linter, choose among a variety of other linter extensions, including [JSHint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.jshint), [JSCS](https://marketplace.visualstudio.com/items?itemName=ms-vscode.jscs), and [JS Standard](https://marketplace.visualstudio.com/items?itemName=chenxsan.vscode-standardjs). + +Read more about setting up JavaScript linters in the VS Code [documentation](/docs/languages/javascript.md#linters). + +![eslint animation](images/extensions/eslint.gif) + +### JavaScript (ES6) code snippets + +Marketplace - [JavaScript (ES6) code snippets](https://marketplace.visualstudio.com/items?itemName=xabikos.JavaScriptSnippets) + +Publisher - [charalampos karypidis](https://marketplace.visualstudio.com/search?term=publisher%3A%22charalampos%20karypidis%22&target=VSCode) + +VS Code comes with many built-in code snippets. The **JavaScript (ES6) code snippets** extension adds snippets for ES6 (ECMAScript 6) syntax. Here is a small sampling of the snippets provided by this extension. See the extension's [README](https://marketplace.visualstudio.com/items?itemName=xabikos.JavaScriptSnippets) to see the dozens of snippets this pack gives you. + +![javascript snippets](images/extensions/javascript_snippets.png) + +You can read more about JavaScript snippets in the VS Code [documentation](/docs/languages/javascript.md#snippets). For additional snippet packs, including [Angular 1](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular1), [Angular 2](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular2), [Bootstrap 3](https://marketplace.visualstudio.com/items?itemName=wcwhitehead.bootstrap-3-snippets), [ReactJs](https://marketplace.visualstudio.com/items?itemName=xabikos.ReactSnippets), and [jQuery](https://marketplace.visualstudio.com/items?itemName=donjayamanne.jquerysnippets), check out the Marketplace's [Snippets category](https://marketplace.visualstudio.com/vscode/Snippets?sortBy=Downloads). + +### npm IntelliSense + +Marketplace - [npm IntelliSense](https://marketplace.visualstudio.com/items?itemName=christian-kohler.npm-intellisense) + +Publisher - [Christian Kohler](https://marketplace.visualstudio.com/search?term=publisher%3A%22Christian%20Kohler%22&target=VSCode) + +This extension provides IntelliSense for npm modules when using `require` or `import`. + +![npm intellisense](images/extensions/npm_intellisense.gif) + +### Debugger for Chrome + +Marketplace - [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) + +Publisher - [Microsoft](https://marketplace.visualstudio.com/search?term=publisher%3A%22Microsoft%22&target=VSCode&sortBy=Relevance) + +When you develop for the front end, you might not see the value of an integrated debugger in your editor. You use the browser's debugger right? This is where the Debugger for Chrome extension comes in. This extension lets you debug your JavaScript code in the Google Chrome browser, or any other targets that support the [Chrome Debugging Protocol](https://chromedevtools.github.io/debugger-protocol-viewer/) while staying in VS Code. No more context switching to debug! + +Prefer to debug using a different browser? You can find extensions for [Edge](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-edge) and [Firefox](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-firefox-debug) as well. + +![debugger for chrome image](images/extensions/chrome_debugger.png) + +### Document This + +Marketplace - [Document This](https://marketplace.visualstudio.com/items?itemName=joelday.docthis) + +Publisher - [Joel Day](https://marketplace.visualstudio.com/search?term=publisher%3A%22Joel%20Day%22&target=VSCode) + +This extension will automatically generate detailed JSDoc comments for your code. + +![document this](images/extensions/document_this.gif) diff --git a/docs/nodejs/images/angular/Welcome-to-app.png b/docs/nodejs/images/angular/Welcome-to-app.png new file mode 100644 index 0000000000000000000000000000000000000000..3e7e8a40422009c1d8099e5874796b94682244a3 Binary files /dev/null and b/docs/nodejs/images/angular/Welcome-to-app.png differ diff --git a/docs/nodejs/images/angular/angular-extensions.png b/docs/nodejs/images/angular/angular-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..9ad2073a0f80565283bb76e4e7c0104c78a64116 Binary files /dev/null and b/docs/nodejs/images/angular/angular-extensions.png differ diff --git a/docs/nodejs/images/angular/bracket-matching.png b/docs/nodejs/images/angular/bracket-matching.png new file mode 100644 index 0000000000000000000000000000000000000000..7b037f26fae2cc1bb3af7e8e0dc3406f22d06f96 Binary files /dev/null and b/docs/nodejs/images/angular/bracket-matching.png differ diff --git a/docs/nodejs/images/angular/breakpoint.png b/docs/nodejs/images/angular/breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..c3cdf8e067c2a43bf68aadbcd47cc213126c8218 Binary files /dev/null and b/docs/nodejs/images/angular/breakpoint.png differ diff --git a/docs/nodejs/images/angular/debug-variable.png b/docs/nodejs/images/angular/debug-variable.png new file mode 100644 index 0000000000000000000000000000000000000000..8393634e1c7529590242207284ebf1bb4dde25ee Binary files /dev/null and b/docs/nodejs/images/angular/debug-variable.png differ diff --git a/docs/nodejs/images/angular/decorator-hover.png b/docs/nodejs/images/angular/decorator-hover.png new file mode 100644 index 0000000000000000000000000000000000000000..34dc049bc52f2f0eead6cec66a10e9c7eda6e1bc Binary files /dev/null and b/docs/nodejs/images/angular/decorator-hover.png differ diff --git a/docs/nodejs/images/angular/hello-world.png b/docs/nodejs/images/angular/hello-world.png new file mode 100644 index 0000000000000000000000000000000000000000..79c0c21f599cff1e94b4231e3adb270e431061c0 Binary files /dev/null and b/docs/nodejs/images/angular/hello-world.png differ diff --git a/docs/nodejs/images/angular/hit-breakpoint.png b/docs/nodejs/images/angular/hit-breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..5720ab28207f2da20bb72eef4c2595c1cef4cd89 Binary files /dev/null and b/docs/nodejs/images/angular/hit-breakpoint.png differ diff --git a/docs/nodejs/images/angular/intellisense.png b/docs/nodejs/images/angular/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..1694ec8d8038773c051abb329c538b0415e005a2 Binary files /dev/null and b/docs/nodejs/images/angular/intellisense.png differ diff --git a/docs/nodejs/images/angular/parameter-help.png b/docs/nodejs/images/angular/parameter-help.png new file mode 100644 index 0000000000000000000000000000000000000000..9c96f48101a7447375433a54f8af09137e9f4da4 Binary files /dev/null and b/docs/nodejs/images/angular/parameter-help.png differ diff --git a/docs/nodejs/images/angular/peek-definition.png b/docs/nodejs/images/angular/peek-definition.png new file mode 100644 index 0000000000000000000000000000000000000000..7cfa9473865e58d9d56b2ca339913fd1fa8532a1 Binary files /dev/null and b/docs/nodejs/images/angular/peek-definition.png differ diff --git a/docs/nodejs/images/angular/suggestions.png b/docs/nodejs/images/angular/suggestions.png new file mode 100644 index 0000000000000000000000000000000000000000..7f8798dbae4f13023ca8fba134b427be6ff45dac Binary files /dev/null and b/docs/nodejs/images/angular/suggestions.png differ diff --git a/docs/nodejs/images/emberjs/bracket-matching.png b/docs/nodejs/images/emberjs/bracket-matching.png new file mode 100644 index 0000000000000000000000000000000000000000..f4219ebc09ab041e9f6005920a2e14a2895c05ba Binary files /dev/null and b/docs/nodejs/images/emberjs/bracket-matching.png differ diff --git a/docs/nodejs/images/emberjs/ember-extensions.png b/docs/nodejs/images/emberjs/ember-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..5a50716349c1dbd14936600bcd30c7c49a07e448 Binary files /dev/null and b/docs/nodejs/images/emberjs/ember-extensions.png differ diff --git a/docs/nodejs/images/emberjs/intellisense.png b/docs/nodejs/images/emberjs/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..3ab6e91fe092cf30ff77618c085951e3c1be2cf7 Binary files /dev/null and b/docs/nodejs/images/emberjs/intellisense.png differ diff --git a/docs/nodejs/images/emberjs/parameter-help.png b/docs/nodejs/images/emberjs/parameter-help.png new file mode 100644 index 0000000000000000000000000000000000000000..1cc545140648d8089f2e54724603f9f5b4a47ddc Binary files /dev/null and b/docs/nodejs/images/emberjs/parameter-help.png differ diff --git a/docs/nodejs/images/emberjs/peek-definition.png b/docs/nodejs/images/emberjs/peek-definition.png new file mode 100644 index 0000000000000000000000000000000000000000..66133693839ce07053dc58c25cc8fb43341ab445 Binary files /dev/null and b/docs/nodejs/images/emberjs/peek-definition.png differ diff --git a/docs/nodejs/images/emberjs/suggestions.png b/docs/nodejs/images/emberjs/suggestions.png new file mode 100644 index 0000000000000000000000000000000000000000..a491837a6d7129c7d7793cc8e2e753e200d18662 Binary files /dev/null and b/docs/nodejs/images/emberjs/suggestions.png differ diff --git a/docs/nodejs/images/emberjs/tomster-logo.png b/docs/nodejs/images/emberjs/tomster-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..ed57c38049a02a87da35be56608b599e9e8376f0 Binary files /dev/null and b/docs/nodejs/images/emberjs/tomster-logo.png differ diff --git a/docs/nodejs/images/emberjs/welcome-page.png b/docs/nodejs/images/emberjs/welcome-page.png new file mode 100644 index 0000000000000000000000000000000000000000..c74d3755fc652e82c10e6b66e3ade0f4bd539ce6 --- /dev/null +++ b/docs/nodejs/images/emberjs/welcome-page.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ea7e9b1ae685bfc8d1720c6ccacacbcd6aa8de6bb0ad143d43d334ec02e92a9a +size 189720 diff --git a/docs/nodejs/images/extensions/chrome_debugger.png b/docs/nodejs/images/extensions/chrome_debugger.png new file mode 100644 index 0000000000000000000000000000000000000000..c3d4a5068a71e8f24595ab7109596afd3643dc2e --- /dev/null +++ b/docs/nodejs/images/extensions/chrome_debugger.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7000291fe613d6f077bd8547517af605aefc8a38179591c3b24a76722afca853 +size 848158 diff --git a/docs/nodejs/images/extensions/document_this.gif b/docs/nodejs/images/extensions/document_this.gif new file mode 100644 index 0000000000000000000000000000000000000000..a1aa4ed439b8c3f22cfb6f66dca8d89d1444a8db --- /dev/null +++ b/docs/nodejs/images/extensions/document_this.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:768de8e496bb661a4d0ac7ff65041c129a9140b30651ddf3c00308a424246a64 +size 194610 diff --git a/docs/nodejs/images/extensions/eslint.gif b/docs/nodejs/images/extensions/eslint.gif new file mode 100644 index 0000000000000000000000000000000000000000..fcb948229164ff07c04117cd7f110489633cab6c Binary files /dev/null and b/docs/nodejs/images/extensions/eslint.gif differ diff --git a/docs/nodejs/images/extensions/javascript_snippets.png b/docs/nodejs/images/extensions/javascript_snippets.png new file mode 100644 index 0000000000000000000000000000000000000000..ab971155801181b055ba1776ba608b7bfc64baca Binary files /dev/null and b/docs/nodejs/images/extensions/javascript_snippets.png differ diff --git a/docs/nodejs/images/extensions/npm_intellisense.gif b/docs/nodejs/images/extensions/npm_intellisense.gif new file mode 100644 index 0000000000000000000000000000000000000000..0826c556943dc409f6c1f0afd23bad883b30057d --- /dev/null +++ b/docs/nodejs/images/extensions/npm_intellisense.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7900f0a3a64e0567668d243596691eaf3592060240d338a1c074d6fe76aac059 +size 502974 diff --git a/docs/nodejs/images/nodejs-debugging/auto-attach-cluster.gif b/docs/nodejs/images/nodejs-debugging/auto-attach-cluster.gif new file mode 100644 index 0000000000000000000000000000000000000000..e379b1f132039ca71c46a0db1a6e4a7506616a53 --- /dev/null +++ b/docs/nodejs/images/nodejs-debugging/auto-attach-cluster.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:43bbbf90dca4e1991488665eb2bfd042799b4e37b00457622e2c5a8079f2fa19 +size 13363509 diff --git a/docs/nodejs/images/nodejs-debugging/auto-attach.gif b/docs/nodejs/images/nodejs-debugging/auto-attach.gif new file mode 100644 index 0000000000000000000000000000000000000000..ef211542fdc704f340da90433de004330f1a63ce --- /dev/null +++ b/docs/nodejs/images/nodejs-debugging/auto-attach.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e98395ac56c9eb8cd680eb4afbc40fb1b0881823a658a9951bd127a973c806df +size 1283216 diff --git a/docs/nodejs/images/nodejs-debugging/breakpointstoolbar.png b/docs/nodejs/images/nodejs-debugging/breakpointstoolbar.png new file mode 100644 index 0000000000000000000000000000000000000000..10c69b5b0150e2abae4e81d3b9d5e75bf51bf416 Binary files /dev/null and b/docs/nodejs/images/nodejs-debugging/breakpointstoolbar.png differ diff --git a/docs/nodejs/images/nodejs-debugging/breakpointsvalidation.png b/docs/nodejs/images/nodejs-debugging/breakpointsvalidation.png new file mode 100644 index 0000000000000000000000000000000000000000..0af4719572ab95507cb798e0a2b71a1ead83d7d6 Binary files /dev/null and b/docs/nodejs/images/nodejs-debugging/breakpointsvalidation.png differ diff --git a/docs/nodejs/images/nodejs-debugging/dimmed-callstack.png b/docs/nodejs/images/nodejs-debugging/dimmed-callstack.png new file mode 100644 index 0000000000000000000000000000000000000000..898d1a2a8bd4960cc3c7eb7a95f671b1ea321fea Binary files /dev/null and b/docs/nodejs/images/nodejs-debugging/dimmed-callstack.png differ diff --git a/docs/nodejs/images/nodejs-debugging/launch-snippets.png b/docs/nodejs/images/nodejs-debugging/launch-snippets.png new file mode 100644 index 0000000000000000000000000000000000000000..073f1b092faddf51c9bc8e7f56884d6e7e9fb6f8 Binary files /dev/null and b/docs/nodejs/images/nodejs-debugging/launch-snippets.png differ diff --git a/docs/nodejs/images/nodejs-debugging/loaded-scripts-explorer.gif b/docs/nodejs/images/nodejs-debugging/loaded-scripts-explorer.gif new file mode 100644 index 0000000000000000000000000000000000000000..f98d7e84bf04b721b3c7e675cc6a1d5024a2170e --- /dev/null +++ b/docs/nodejs/images/nodejs-debugging/loaded-scripts-explorer.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:defc292ba465192655bfb899d66754963334b9fa48deab1c995a65273edbbedf +size 5621068 diff --git a/docs/nodejs/images/nodejs-debugging/loaded-scripts.gif b/docs/nodejs/images/nodejs-debugging/loaded-scripts.gif new file mode 100644 index 0000000000000000000000000000000000000000..84bbab0f53b6540c07f0ee8b864f52e811f19889 --- /dev/null +++ b/docs/nodejs/images/nodejs-debugging/loaded-scripts.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8755135c7cc5c11d109a7fc582a595e670d6984dd45ade3b058de155af24a7f0 +size 4603858 diff --git a/docs/nodejs/images/nodejs-debugging/process-picker.png b/docs/nodejs/images/nodejs-debugging/process-picker.png new file mode 100644 index 0000000000000000000000000000000000000000..802b01f08ef3537a951ffcc180f2fc3e654dc1c5 Binary files /dev/null and b/docs/nodejs/images/nodejs-debugging/process-picker.png differ diff --git a/docs/nodejs/images/nodejs-deployment/azure-app-service-tools.png b/docs/nodejs/images/nodejs-deployment/azure-app-service-tools.png new file mode 100644 index 0000000000000000000000000000000000000000..9fba38f34b2154e498087f32c8312f3a9139708e Binary files /dev/null and b/docs/nodejs/images/nodejs-deployment/azure-app-service-tools.png differ diff --git a/docs/nodejs/images/nodejs/app-js-breakpoint-set.png b/docs/nodejs/images/nodejs/app-js-breakpoint-set.png new file mode 100644 index 0000000000000000000000000000000000000000..c26ed80e4a5a9d99a9ad5183bd469632c0b43368 Binary files /dev/null and b/docs/nodejs/images/nodejs/app-js-breakpoint-set.png differ diff --git a/docs/nodejs/images/nodejs/app-js-file-created.png b/docs/nodejs/images/nodejs/app-js-file-created.png new file mode 100644 index 0000000000000000000000000000000000000000..936023bcb928b2615a6c8c79e8b85bd5103c76c4 Binary files /dev/null and b/docs/nodejs/images/nodejs/app-js-file-created.png differ diff --git a/docs/nodejs/images/nodejs/consoleintellisense.png b/docs/nodejs/images/nodejs/consoleintellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..493ab9e0f001679eb5c5ffc4ebc5e13ab62d705a Binary files /dev/null and b/docs/nodejs/images/nodejs/consoleintellisense.png differ diff --git a/docs/nodejs/images/nodejs/debugicon.png b/docs/nodejs/images/nodejs/debugicon.png new file mode 100644 index 0000000000000000000000000000000000000000..60c1745fd186f7a62a0825883c03afbd51b5c8f9 Binary files /dev/null and b/docs/nodejs/images/nodejs/debugicon.png differ diff --git a/docs/nodejs/images/nodejs/debugsession.png b/docs/nodejs/images/nodejs/debugsession.png new file mode 100644 index 0000000000000000000000000000000000000000..c8b2bf5d00cb7de35712994d98a800eaaacc5f33 --- /dev/null +++ b/docs/nodejs/images/nodejs/debugsession.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:53e53d7f243a2510aeedf0749d614d84f2e3c169c4938e4cc59aa11f8674b993 +size 134557 diff --git a/docs/nodejs/images/nodejs/express.png b/docs/nodejs/images/nodejs/express.png new file mode 100644 index 0000000000000000000000000000000000000000..8c2e1648e2307d287c53631beb116215e72b7c6c Binary files /dev/null and b/docs/nodejs/images/nodejs/express.png differ diff --git a/docs/nodejs/images/nodejs/hello-world-debugging.png b/docs/nodejs/images/nodejs/hello-world-debugging.png new file mode 100644 index 0000000000000000000000000000000000000000..602e41b3e3acfef620baacb3d8b8b7e93a9a6736 --- /dev/null +++ b/docs/nodejs/images/nodejs/hello-world-debugging.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:50a5b36db366f88b076c692102d06d211b971b55b2a1cab9f049cae99971018f +size 115570 diff --git a/docs/nodejs/images/nodejs/hello-world-launch-json.png b/docs/nodejs/images/nodejs/hello-world-launch-json.png new file mode 100644 index 0000000000000000000000000000000000000000..77bf9ad55fe56c5d32ed49b74539a9d3f41356fa Binary files /dev/null and b/docs/nodejs/images/nodejs/hello-world-launch-json.png differ diff --git a/docs/nodejs/images/nodejs/hover.png b/docs/nodejs/images/nodejs/hover.png new file mode 100644 index 0000000000000000000000000000000000000000..a0146627805ab6715ca1ce3ceb4ca90a3bcd05eb Binary files /dev/null and b/docs/nodejs/images/nodejs/hover.png differ diff --git a/docs/nodejs/images/nodejs/integrated-terminal.png b/docs/nodejs/images/nodejs/integrated-terminal.png new file mode 100644 index 0000000000000000000000000000000000000000..cb4c91ac559ec11d0d75472372808aee1ab775ff Binary files /dev/null and b/docs/nodejs/images/nodejs/integrated-terminal.png differ diff --git a/docs/nodejs/images/nodejs/intellisense.png b/docs/nodejs/images/nodejs/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..2a79ec4db8a0cfdcd5bc31ae13680834ad562935 Binary files /dev/null and b/docs/nodejs/images/nodejs/intellisense.png differ diff --git a/docs/nodejs/images/nodejs/launchjson.png b/docs/nodejs/images/nodejs/launchjson.png new file mode 100644 index 0000000000000000000000000000000000000000..3952a86cc51a23ee63c4343c5486d16584c53dca Binary files /dev/null and b/docs/nodejs/images/nodejs/launchjson.png differ diff --git a/docs/nodejs/images/nodejs/moduleintellisense.png b/docs/nodejs/images/nodejs/moduleintellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..19c7e4f9339fc4e20b89297d87a591be1497d660 Binary files /dev/null and b/docs/nodejs/images/nodejs/moduleintellisense.png differ diff --git a/docs/nodejs/images/nodejs/runtimes_node.png b/docs/nodejs/images/nodejs/runtimes_node.png new file mode 100644 index 0000000000000000000000000000000000000000..50289b8fa447efd8e45434399da12ca36dda0b07 --- /dev/null +++ b/docs/nodejs/images/nodejs/runtimes_node.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:01ddfddb9057e152c53bb4be6b9ca45be5870aa051366c777c193274f89757cc +size 132010 diff --git a/docs/nodejs/images/nodejs/stringintellisense.png b/docs/nodejs/images/nodejs/stringintellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..c5d22039ba73594dae5d8709cb5ecb6bd9ce80be Binary files /dev/null and b/docs/nodejs/images/nodejs/stringintellisense.png differ diff --git a/docs/nodejs/images/nodejs/toolbar-new-file.png b/docs/nodejs/images/nodejs/toolbar-new-file.png new file mode 100644 index 0000000000000000000000000000000000000000..d3da114f1ae298a773240bb993fe797db4fabe60 Binary files /dev/null and b/docs/nodejs/images/nodejs/toolbar-new-file.png differ diff --git a/docs/nodejs/images/nodejs/warning.png b/docs/nodejs/images/nodejs/warning.png new file mode 100644 index 0000000000000000000000000000000000000000..146ccaa1cc0860e9907b3744d7f6c008047bfd42 Binary files /dev/null and b/docs/nodejs/images/nodejs/warning.png differ diff --git a/docs/nodejs/images/reactjs/app-is-unused.png b/docs/nodejs/images/reactjs/app-is-unused.png new file mode 100644 index 0000000000000000000000000000000000000000..926d2d195a8481f96fa3df54045613ee4e3fcfc3 Binary files /dev/null and b/docs/nodejs/images/reactjs/app-is-unused.png differ diff --git a/docs/nodejs/images/reactjs/bracket-matching.png b/docs/nodejs/images/reactjs/bracket-matching.png new file mode 100644 index 0000000000000000000000000000000000000000..ba0a8e5856c3dad12d4f744cbb48c78993f2efd6 Binary files /dev/null and b/docs/nodejs/images/reactjs/bracket-matching.png differ diff --git a/docs/nodejs/images/reactjs/breakpoint.png b/docs/nodejs/images/reactjs/breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..95d37e4153c5d2bcc8be1afb78c63f1184c53d69 Binary files /dev/null and b/docs/nodejs/images/reactjs/breakpoint.png differ diff --git a/docs/nodejs/images/reactjs/chrome-debugger-readme.png b/docs/nodejs/images/reactjs/chrome-debugger-readme.png new file mode 100644 index 0000000000000000000000000000000000000000..608a01cbc2651ee2de45980dccee04dd36e75104 Binary files /dev/null and b/docs/nodejs/images/reactjs/chrome-debugger-readme.png differ diff --git a/docs/nodejs/images/reactjs/create-eslintrc.png b/docs/nodejs/images/reactjs/create-eslintrc.png new file mode 100644 index 0000000000000000000000000000000000000000..fe2744c8e6b87044529a721b53fa44cecb70d514 Binary files /dev/null and b/docs/nodejs/images/reactjs/create-eslintrc.png differ diff --git a/docs/nodejs/images/reactjs/debug-config.png b/docs/nodejs/images/reactjs/debug-config.png new file mode 100644 index 0000000000000000000000000000000000000000..81b5a2217d21b5dc1222498c16812d570909fa9e Binary files /dev/null and b/docs/nodejs/images/reactjs/debug-config.png differ diff --git a/docs/nodejs/images/reactjs/debug-variable.png b/docs/nodejs/images/reactjs/debug-variable.png new file mode 100644 index 0000000000000000000000000000000000000000..6755f737a0ce8641b9ea868a6949348f56c3a5cb Binary files /dev/null and b/docs/nodejs/images/reactjs/debug-variable.png differ diff --git a/docs/nodejs/images/reactjs/debugger-for-chrome.png b/docs/nodejs/images/reactjs/debugger-for-chrome.png new file mode 100644 index 0000000000000000000000000000000000000000..1d6b79c7563a15b8d7e4c55a71401dac0d57aad1 Binary files /dev/null and b/docs/nodejs/images/reactjs/debugger-for-chrome.png differ diff --git a/docs/nodejs/images/reactjs/eslint-extension.png b/docs/nodejs/images/reactjs/eslint-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..03aa611541bbf594e2cf6b9d6eec379c19e30840 Binary files /dev/null and b/docs/nodejs/images/reactjs/eslint-extension.png differ diff --git a/docs/nodejs/images/reactjs/eslintrc-intellisense.png b/docs/nodejs/images/reactjs/eslintrc-intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..04ecb5dda36d3c7723fff656dde78e1cb5b587bf Binary files /dev/null and b/docs/nodejs/images/reactjs/eslintrc-intellisense.png differ diff --git a/docs/nodejs/images/reactjs/extra-semi-error.png b/docs/nodejs/images/reactjs/extra-semi-error.png new file mode 100644 index 0000000000000000000000000000000000000000..f9a619f9074df1523aff5adec12808908db204be Binary files /dev/null and b/docs/nodejs/images/reactjs/extra-semi-error.png differ diff --git a/docs/nodejs/images/reactjs/hello-world.png b/docs/nodejs/images/reactjs/hello-world.png new file mode 100644 index 0000000000000000000000000000000000000000..4d7c3669a07c5b10a1d153697b67821f9c771133 Binary files /dev/null and b/docs/nodejs/images/reactjs/hello-world.png differ diff --git a/docs/nodejs/images/reactjs/hit-breakpoint.png b/docs/nodejs/images/reactjs/hit-breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..ba7f5df8bd12e2412d7b355db8a60e065c619249 --- /dev/null +++ b/docs/nodejs/images/reactjs/hit-breakpoint.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:26296914d216d4e22673af091bfb5fb3d93f649eb5c3e738123fce1673329d56 +size 110174 diff --git a/docs/nodejs/images/reactjs/intellisense.png b/docs/nodejs/images/reactjs/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..aa4e1f9e642f14cd3a97604e7057b9d19ff95e90 Binary files /dev/null and b/docs/nodejs/images/reactjs/intellisense.png differ diff --git a/docs/nodejs/images/reactjs/js-error.png b/docs/nodejs/images/reactjs/js-error.png new file mode 100644 index 0000000000000000000000000000000000000000..760dd47803869ed4d68906c031b3aa0f3d029e51 Binary files /dev/null and b/docs/nodejs/images/reactjs/js-error.png differ diff --git a/docs/nodejs/images/reactjs/jsx-intellisense.png b/docs/nodejs/images/reactjs/jsx-intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..8683a3cd1ba8ebda04e3e7d7a2e93050ef632ea0 Binary files /dev/null and b/docs/nodejs/images/reactjs/jsx-intellisense.png differ diff --git a/docs/nodejs/images/reactjs/markdown-preview.png b/docs/nodejs/images/reactjs/markdown-preview.png new file mode 100644 index 0000000000000000000000000000000000000000..8833fa3c568714b1b902b45ad7058017356e5bca Binary files /dev/null and b/docs/nodejs/images/reactjs/markdown-preview.png differ diff --git a/docs/nodejs/images/reactjs/parameter-help.png b/docs/nodejs/images/reactjs/parameter-help.png new file mode 100644 index 0000000000000000000000000000000000000000..413c409e993ef2bc2b36a7a9c159bbea21dbc0f6 Binary files /dev/null and b/docs/nodejs/images/reactjs/parameter-help.png differ diff --git a/docs/nodejs/images/reactjs/peek-definition.png b/docs/nodejs/images/reactjs/peek-definition.png new file mode 100644 index 0000000000000000000000000000000000000000..4449410eb90c4dc519969854c4417221b205070a Binary files /dev/null and b/docs/nodejs/images/reactjs/peek-definition.png differ diff --git a/docs/nodejs/images/reactjs/suggestions.png b/docs/nodejs/images/reactjs/suggestions.png new file mode 100644 index 0000000000000000000000000000000000000000..ce93b82acd67435c3cd94818c0bcb42104501377 Binary files /dev/null and b/docs/nodejs/images/reactjs/suggestions.png differ diff --git a/docs/nodejs/images/reactjs/welcome-to-react.png b/docs/nodejs/images/reactjs/welcome-to-react.png new file mode 100644 index 0000000000000000000000000000000000000000..27431207c46fff86725fcbb30b3e5364b1e2797c Binary files /dev/null and b/docs/nodejs/images/reactjs/welcome-to-react.png differ diff --git a/docs/nodejs/images/recipes/chrome.png b/docs/nodejs/images/recipes/chrome.png new file mode 100644 index 0000000000000000000000000000000000000000..6df5292c44e75eb43c1a680d4152ef334466e48f --- /dev/null +++ b/docs/nodejs/images/recipes/chrome.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3c3b7fe54b6d940db888b6882de0506c6e76dcb28c608116130eb67fa97d6785 +size 201386 diff --git a/docs/nodejs/images/recipes/electron.png b/docs/nodejs/images/recipes/electron.png new file mode 100644 index 0000000000000000000000000000000000000000..4686833a240dfe5b52edd55b385fced132234b19 --- /dev/null +++ b/docs/nodejs/images/recipes/electron.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2fdcd49b668faedefdfabdfcb4f6946ef9634f7c6bbb709f26fee2bec25d56e0 +size 145608 diff --git a/docs/nodejs/images/recipes/mern.png b/docs/nodejs/images/recipes/mern.png new file mode 100644 index 0000000000000000000000000000000000000000..4cac6f0b6d836c7a1bc36d20f751f60cb0997172 --- /dev/null +++ b/docs/nodejs/images/recipes/mern.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:aaea9cb211bb3bf679d62266e7915ad7209ef9102610a6d93e48f8564871e20f +size 658296 diff --git a/docs/nodejs/images/recipes/node-typescript-docker.png b/docs/nodejs/images/recipes/node-typescript-docker.png new file mode 100644 index 0000000000000000000000000000000000000000..1bbadf65002da9ff6c84381c009a370cea99399f --- /dev/null +++ b/docs/nodejs/images/recipes/node-typescript-docker.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c2fec0a805dd1e5f1e16ca775242a7821faf84b84743ab00b3a17e3664fafa29 +size 183124 diff --git a/docs/nodejs/images/recipes/nodejs.png b/docs/nodejs/images/recipes/nodejs.png new file mode 100644 index 0000000000000000000000000000000000000000..a04aa58eceb9c09f3b4d70a99e118420c2d02389 --- /dev/null +++ b/docs/nodejs/images/recipes/nodejs.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e5b4efb851fe868bf7a60b7335e671fd0486974ecbe7c0cd8b15e2a56dfb5b42 +size 116992 diff --git a/docs/nodejs/images/vuejs/breakpoint.png b/docs/nodejs/images/vuejs/breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..568aca553dbab6928890e1b9071fa6b00e243f59 Binary files /dev/null and b/docs/nodejs/images/vuejs/breakpoint.png differ diff --git a/docs/nodejs/images/vuejs/debugger-for-chrome.png b/docs/nodejs/images/vuejs/debugger-for-chrome.png new file mode 100644 index 0000000000000000000000000000000000000000..1d6b79c7563a15b8d7e4c55a71401dac0d57aad1 Binary files /dev/null and b/docs/nodejs/images/vuejs/debugger-for-chrome.png differ diff --git a/docs/nodejs/images/vuejs/hello-world.png b/docs/nodejs/images/vuejs/hello-world.png new file mode 100644 index 0000000000000000000000000000000000000000..a37475e831781b3ed6597ac579ece7461578b3a3 Binary files /dev/null and b/docs/nodejs/images/vuejs/hello-world.png differ diff --git a/docs/nodejs/images/vuejs/javascript-suggestions.png b/docs/nodejs/images/vuejs/javascript-suggestions.png new file mode 100644 index 0000000000000000000000000000000000000000..4d99269b4fdefc21727b3aac9f332a381ceee508 Binary files /dev/null and b/docs/nodejs/images/vuejs/javascript-suggestions.png differ diff --git a/docs/nodejs/images/vuejs/peek-definition.png b/docs/nodejs/images/vuejs/peek-definition.png new file mode 100644 index 0000000000000000000000000000000000000000..81be11e34f8aa2b35cb21485a292be5de5b269df Binary files /dev/null and b/docs/nodejs/images/vuejs/peek-definition.png differ diff --git a/docs/nodejs/images/vuejs/suggestions.png b/docs/nodejs/images/vuejs/suggestions.png new file mode 100644 index 0000000000000000000000000000000000000000..0891b452dd2277da31ca1f86dce27fca6c02c1e2 Binary files /dev/null and b/docs/nodejs/images/vuejs/suggestions.png differ diff --git a/docs/nodejs/images/vuejs/vetur-extension-recommendation.png b/docs/nodejs/images/vuejs/vetur-extension-recommendation.png new file mode 100644 index 0000000000000000000000000000000000000000..9ff9c61e8a1b794166038063a39b07b345959145 Binary files /dev/null and b/docs/nodejs/images/vuejs/vetur-extension-recommendation.png differ diff --git a/docs/nodejs/images/vuejs/vetur-extension.png b/docs/nodejs/images/vuejs/vetur-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..0ed77d01578d7d5612760085916d5657a652d3f1 Binary files /dev/null and b/docs/nodejs/images/vuejs/vetur-extension.png differ diff --git a/docs/nodejs/images/vuejs/vue-extension-pack.png b/docs/nodejs/images/vuejs/vue-extension-pack.png new file mode 100644 index 0000000000000000000000000000000000000000..ce7402ae92f7aae18c00d5a0b9ec4a9348b4c69b Binary files /dev/null and b/docs/nodejs/images/vuejs/vue-extension-pack.png differ diff --git a/docs/nodejs/images/vuejs/vue-extensions.png b/docs/nodejs/images/vuejs/vue-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..bbba5f2e1ac3d0f068c1de7db1631a31334faa3a Binary files /dev/null and b/docs/nodejs/images/vuejs/vue-extensions.png differ diff --git a/docs/nodejs/images/vuejs/vue-language-features.png b/docs/nodejs/images/vuejs/vue-language-features.png new file mode 100644 index 0000000000000000000000000000000000000000..3426b2ff73905cd74f9807c7fd108fc3484876bd Binary files /dev/null and b/docs/nodejs/images/vuejs/vue-language-features.png differ diff --git a/docs/nodejs/images/vuejs/vue-linting.png b/docs/nodejs/images/vuejs/vue-linting.png new file mode 100644 index 0000000000000000000000000000000000000000..a094c8be2683b592e510b070c264eb3eb16621c7 Binary files /dev/null and b/docs/nodejs/images/vuejs/vue-linting.png differ diff --git a/docs/nodejs/images/vuejs/welcome-to-vue.png b/docs/nodejs/images/vuejs/welcome-to-vue.png new file mode 100644 index 0000000000000000000000000000000000000000..070bd10ffd51e2c6629c304d1f8d12a61def871a Binary files /dev/null and b/docs/nodejs/images/vuejs/welcome-to-vue.png differ diff --git a/docs/nodejs/images/working-with-javascript/checkjs-example.gif b/docs/nodejs/images/working-with-javascript/checkjs-example.gif new file mode 100644 index 0000000000000000000000000000000000000000..754b0cb95e747fd1eb17fb810327a140d0db2a4d --- /dev/null +++ b/docs/nodejs/images/working-with-javascript/checkjs-example.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:99174e3201f938c8e94d7b17de3844b6a782b41b86ad4bcfea8ee066a039446f +size 2408672 diff --git a/docs/nodejs/images/working-with-javascript/complex_jsconfig_setup.png b/docs/nodejs/images/working-with-javascript/complex_jsconfig_setup.png new file mode 100644 index 0000000000000000000000000000000000000000..4a879b5954f3e6affca57047271d092c1b6cce1f Binary files /dev/null and b/docs/nodejs/images/working-with-javascript/complex_jsconfig_setup.png differ diff --git a/docs/nodejs/images/working-with-javascript/disable-TS-language.png b/docs/nodejs/images/working-with-javascript/disable-TS-language.png new file mode 100644 index 0000000000000000000000000000000000000000..206c89100b3b82eb0a2eaba793df2d2264c0f334 --- /dev/null +++ b/docs/nodejs/images/working-with-javascript/disable-TS-language.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:af06f4bec8b4c350d4a964d67d1aaafbce2385a36ff571df72e8b8529cdd9410 +size 102579 diff --git a/docs/nodejs/images/working-with-javascript/jsconfig_setup.png b/docs/nodejs/images/working-with-javascript/jsconfig_setup.png new file mode 100644 index 0000000000000000000000000000000000000000..a5ba4d82a1f2f449b2be5989073d376cdfc454f7 Binary files /dev/null and b/docs/nodejs/images/working-with-javascript/jsconfig_setup.png differ diff --git a/docs/nodejs/images/working-with-javascript/lodash-typings.png b/docs/nodejs/images/working-with-javascript/lodash-typings.png new file mode 100644 index 0000000000000000000000000000000000000000..20c684271852b4c8e83264d930d05ab90c65f208 Binary files /dev/null and b/docs/nodejs/images/working-with-javascript/lodash-typings.png differ diff --git a/docs/nodejs/nodejs-debugging.md b/docs/nodejs/nodejs-debugging.md new file mode 100644 index 0000000000000000000000000000000000000000..d54f2c6349c3d019032e93f3a03ae27a70f203e1 --- /dev/null +++ b/docs/nodejs/nodejs-debugging.md @@ -0,0 +1,652 @@ +--- +Order: 3 +Area: nodejs +TOCTitle: Node.js Debugging +ContentId: 3AC4DBB5-1469-47FD-9CC2-6C94684D4A9D +PageTitle: Debug Node.js Apps using Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: The Visual Studio Code editor includes Node.js debugging support. Set breakpoints, step-in, inspect variables and more. +MetaSocialImage: /assets/docs/editor/debugging/Debugging.png +--- +# Node.js debugging in VS Code + +The Visual Studio Code editor has built-in debugging support for the [Node.js](https://nodejs.org/) runtime and can debug JavaScript, TypeScript, and many other languages that are transpiled into JavaScript. Setting up a project for Node.js debugging is usually straightforward with VS Code providing appropriate launch configuration defaults and snippets. + +>**Note**: If you are just getting started with VS Code, you can learn about general debugging features and creating `launch.json` configuration files in the [Debugging](/docs/editor/debugging.md) topic. + +This Node.js debugging document goes into more detail about configurations and features for more advanced debugging scenarios. You'll find instruction for debugging with [source maps](/docs/nodejs/nodejs-debugging.md#source-maps), [stepping over external code](/docs/nodejs/nodejs-debugging.md#skipping-uninteresting-code-node-chrome), doing [remote debugging](/docs/nodejs/nodejs-debugging.md#remote-debugging), and much more. + +If you'd like to watch an introductory video, see [Getting started with Node.js debugging](https://www.youtube.com/watch?v=2oFKNL7vYV8). + +## Supported Node-like runtimes + +Since the VS Code Node.js debugger communicates to the Node.js runtimes through [wire protocols](https://en.wikipedia.org/wiki/Wire_protocol), the set of supported runtimes is determined by all runtimes supporting the wire protocols. + +Today two wire protocols exist: + +- **legacy**: the original [V8 Debugger Protocol](https://github.com/buggerjs/bugger-v8-client/blob/master/PROTOCOL.md) which is currently supported by older runtimes. +- **inspector**: the new [V8 Inspector Protocol](https://chromedevtools.github.io/debugger-protocol-viewer/v8/) is exposed via the `--inspect` flag in Node.js versions >= 6.3. It addresses most of the limitations and scalability issues of the legacy protocol. + +Currently these protocols are supported by specific version ranges of the following runtimes: + +Runtime | 'Legacy' Protocol | 'Inspector' Protocol +----------|-------------------|---------- +io.js | all | no +Node.js | < 8.x | >= 6.3 (Windows: >= 6.9) +Electron | < 1.7.4 | >= 1.7.4 +Chakra | all | not yet + +Although it appears to be possible that the VS Code Node.js debugger picks the best protocol always automatically, +we've decided for a 'pessimistic approach' with an explicit launch configuration attribute `protocol` and the following values: + +- **`auto`**: tries to automatically detect the protocol used by the targeted runtime. For configurations of request type `launch` and if no `runtimeExecutable` is specified, we try to determine the version by running node from the PATH with an `--version` argument. If the node version is >= 8.0, the new 'inspector' protocol is used. For configurations of request type 'attach', we try to connect with the new protocol and if this works, we use the 'inspector' protocol. We only switch to the new 'inspector' protocol for versions >= 6.9 because of severe problems in earlier versions. +- **`inspector`**: forces the node debugger to use the 'inspector' protocol based implementation. This is supported by node versions >= 6.3 and Electron versions >= 1.7.4. +- **`legacy`**: forces the node debugger to use the 'legacy' protocol based implementation. This is supported by node versions < v8.0 and Electron versions < 1.7.4. + +Starting with VS Code 1.11, the default value for the `protocol` attribute is `auto`. + +If your runtime supports both protocols, here are a few additional reasons for using the `inspector` protocol over `legacy`: + +* It can be more stable when debugging very large JavaScript objects. The legacy protocol can become painfully slow when sending large values between the client and server. +* If you are using an ES6 Proxy in your app, you can prevent a Node v7+ runtime from crashing when being debugged via the `inspector` protocol. This issue is tracked in [Microsoft/vscode#12749](https://github.com/Microsoft/vscode/issues/12749). +* Debugging via the `inspector` protocol can handle some trickier source map setups. If you have trouble setting breakpoints in source mapped files, try using `inspector`. + +We try to keep feature parity between both protocol implementations but this becomes more and more difficult because the technology underlying `legacy` is deprecated whereas the new `inspector` evolves quickly. For this reason, we specify the supported protocols if a features is not supported by both `legacy` and `inspector`. + +## Launch configuration attributes + +Debugging configurations are stored in a `launch.json` file located in your workspace's `.vscode` folder. An introduction into the creation and use of debugging configuration files is in the general [Debugging](/docs/editor/debugging.md#launch-configurations) topic. + +Below is a reference on `launch.json` attributes specific to the Node.js debugger. + +The following attributes are supported in launch configurations of type `launch` and `attach`: + +* `protocol` - debug protocol to use. See section [Supported Node-like runtimes](/docs/nodejs/nodejs-debugging.md#supported-nodelike-runtimes) above. +* `port` - debug port to use. See sections [Attaching to Node.js](/docs/nodejs/nodejs-debugging.md#attaching-to-nodejs) and [Remote debugging](/docs/nodejs/nodejs-debugging.md#remote-debugging). +* `address` - TCP/IP address of the debug port. See sections [Attaching to Node.js](/docs/nodejs/nodejs-debugging.md#attaching-to-nodejs) and [Remote debugging](/docs/nodejs/nodejs-debugging.md#remote-debugging). +* `sourceMaps` - enable source maps by setting this to `true`. See section [Source maps](/docs/nodejs/nodejs-debugging.md#source-maps). +* `outFiles` - array of glob patterns for locating generated JavaScript files. See section [Source maps](/docs/nodejs/nodejs-debugging.md#source-maps). +* `restart` - restart session on termination. See section [Restarting debug session automatically](/docs/nodejs/nodejs-debugging.md#restarting-debug-sessions-automatically-when-source-is-edited). +* `autoAttachChildProcesses` - track all subprocesses of debuggee and automatically attach to those that are launched in debug mode. See section [Automatically attach debugger to Node.js subprocesses](/docs/nodejs/nodejs-debugging.md#automatically-attach-debugger-to-nodejs-subprocesses) below. +* `timeout` - when restarting a session, give up after this number of milliseconds. See section [Attaching to Node.js](/docs/nodejs/nodejs-debugging.md#attaching-to-nodejs). +* `stopOnEntry` - break immediately when the program launches. +* `localRoot` - VS Code's root directory. See section [Remote debugging](/docs/nodejs/nodejs-debugging.md#remote-debugging) below. +* `remoteRoot` - Node's root directory. See section [Remote debugging](/docs/nodejs/nodejs-debugging.md#remote-debugging) below. +* `smartStep`- try to automatically step over code that doesn't map to source files. See section [Smart stepping](/docs/nodejs/nodejs-debugging.md#smart-stepping). +* `skipFiles` - automatically skip files covered by these glob patterns. See section [Skipping uninteresting code](/docs/nodejs/nodejs-debugging.md#skipping-uninteresting-code-node-chrome). +* `trace` - enable diagnostic output. + +These attributes are only available for launch configurations of request type `launch`: + +* `program` - an absolute path to the Node.js program to debug. +* `args` - arguments passed to the program to debug. This attribute is of type array and expects individual arguments as array elements. +* `cwd` - launch the program to debug in this directory. +* `runtimeExecutable` - absolute path to the runtime executable to be used. Default is `node`. See section [Launch configuration support for 'npm' and other tools](/docs/nodejs/nodejs-debugging.md#launch-configuration-support-for-npm-and-other-tools). +* `runtimeArgs` - optional arguments passed to the runtime executable. +* `runtimeVersion` - if "[nvm](https://github.com/creationix/nvm)" (or "[nvm-windows](https://github.com/coreybutler/nvm-windows)") or "[nvs](https://github.com/jasongin/nvs)" is used for managing Node.js versions, this attribute can be used to select a specific version of Node.js. See section [Multi version support](/docs/nodejs/nodejs-debugging.md#multi-version-support) below. +* `env` - optional environment variables. This attribute expects environment variables as a list of string typed key/value pairs. +* `envFile` - optional path to a file containing environment variable definitions. See section [Load environment variables from external file](/docs/nodejs/nodejs-debugging.md#load-environment-variables-from-external-file-node) below. +* `console` - kind of console to launch the program (`internalConsole`, `integratedTerminal`, `externalTerminal`). See section [Node Console](/docs/nodejs/nodejs-debugging.md#node-console) below. + +This attribute is only available for launch configurations of request type `attach`: + +* `processId` - the debugger tries to attach to this process after having sent a USR1 signal. With this setting, the debugger can attach to an already running process that was not started in debug mode. When using the `processId` attribute the debug port is determined automatically based on the Node.js version (and the used protocol) and cannot be configured explicitly. So don't specify a `port` attribute. + +### Launch configurations for common scenarios + +You can use IntelliSense to add launch configuration snippets for commonly used Node.js debugging scenarios to a `launch.json` file. + +![Launch configuration snippets for Node.js](images/nodejs-debugging/launch-snippets.png) + +Here is the list of all snippets: + +- **Launch Program**: Launch a Node.js program in debug mode. +- **Launch via npm**: Launch a Node.js program through an npm 'debug' script. If you have defined an npm debug script in your package.json, you can use this directly from your launch configuration. Make sure that the debug port used in the npm script, corresponds to the port specified in the snippet. +- **Attach**: Attach to the debug port of a locally running Node.js program. Make sure that the Node.js program to debug has been started in debug mode and the debug port used is the same as the one specified in the snippet. +- **Attach to Remote Program**: Attach to the debug port of a Node.js program running on the host specified by the `address` attribute. Make sure that the Node.js program to debug has been started in debug mode and the debug port used is the same as the one specified in the snippet. To help VS Code mapping source files between your workspace and the filesystem of the remote host, make sure to specify correct paths for the `localRoot`and `remoteRoot` attributes. +- **Attach by Process ID**: Open the process picker to select a node or gulp process for debugging. With this launch configuration you can even attach to a node or gulp process that was not started in debug mode. +- **Nodemon Setup**: Use nodemon to relaunch a debug session automatically whenever the JavaScript source has changed. Make sure that you have nodemon installed globally. Please note that terminating the debug session only terminates the program to debug, not nodemon itself. To terminate nodemon, press `kbstyle(Ctrl+C)` in the Integrated Terminal. +- **Mocha Tests**: Debug mocha tests in a `test` folder of your project. Make sure that your project has 'mocha' installed in its `node_modules` folder. +- **Yeoman generator**: Debug a yeoman generator. The snippet asks you to specify the name of the generator. Make sure that your project has 'yo' installed in its `node_modules` folder and that your generated project has been installed for debugging by running `npm link` in the project folder. +- **Gulp task**: Debug a gulp task. Make sure that your project has 'gulp' installed in its `node_modules` folder. +- **Electron Main**: Debug the main Node.js process of an Electron application. The snippet assumes that the Electron executable has been installed inside the `node_modules/.bin` directory of the workspace. + +### Node console + +By default, Node.js debug sessions launch the target in the internal VS Code Debug Console. Since the Debug Console does not support programs that need to read input from the console, you can enable either an external terminal or use the VS Code Integrated Terminal by setting the `console` attribute in your launch configuration to `externalTerminal` or `integratedTerminal` respectively. The default is `internalConsole`. + +If an external terminal is used, you can configure which terminal program to use via the `terminal.external.windowsExec`, `terminal.external.osxExec`, and `terminal.external.linuxExec` settings. + +### Launch configuration support for 'npm' and other tools + +Instead of launching the Node.js program directly with node, you can use 'npm' scripts or other task runner tools directly from a launch configuration: + +- Any program available on the PATH (for example 'npm', 'mocha', 'gulp', etc.) can be used for the `runtimeExecutable` attribute and arguments can be passed via `runtimeArgs`. +- You do not have to set the `program` attribute if your npm script or other tool implicitly specifies the program to launch. +- If you specify a debug port via the `port` attribute, VS Code will not automatically add the `--inspect-brk=nnnn` attribute because the debug port is typically specified by the npm script or other tool as well. + +Let's look at an 'npm' example. If your `package.json` has a 'debug' script, for example: + +```json + "scripts": { + "debug": "node --nolazy --inspect-brk=9229 myProgram.js" + }, +``` + +the corresponding launch configuration would look like this: + +```json +{ + "name": "Launch via npm", + "type": "node", + "request": "launch", + "cwd": "${workspaceFolder}", + "runtimeExecutable": "npm", + "runtimeArgs": [ + "run-script", "debug" + ], + "port": 9229 +} +``` + +### Multi version support + +If you are using '[nvm](https://github.com/creationix/nvm)' (or '[nvm-windows](https://github.com/coreybutler/nvm-windows)') to manage your Node.js versions, it is possible to specify a `runtimeVersion` attribute in a launch configuration for selecting a specific version of Node.js: + +```json +{ + "type": "node", + "request": "launch", + "name": "Launch test", + "runtimeVersion": "7.10.1", + "program": "${workspaceFolder}/test.js" +} +``` + +If you are using '[nvs](https://github.com/jasongin/nvs)' to manage your Node.js versions, it is possible to use `runtimeVersion` attribute to select a specific version of Node.js: + +```json +{ + "type": "node", + "request": "launch", + "name": "Launch test", + "runtimeVersion": "chackracore/8.9.4/x64", + "program": "${workspaceFolder}/test.js" +} +``` + +Make sure to have those Node.js versions installed that you want to use with the `runtimeVersion` attribute as the feature will not download and install the version itself. So you will have to run something like `nvm install 7.10.1` or `nvs add 7.10.1` from the integrated terminal if you plan to add `"runtimeVersion": "7.10.1"` to your launch configuration. + +>**Note:** If VS Code detects that "nvs" is installed, it does **not** fall back to "nvm" if a specific Node.js version cannot be found in "nvs". Using both "nvs" and "nvm" at the same time is not supported. + +### Load environment variables from external file (node) + +The VS Code Node debugger supports loading environment variables from a file and passing them to the Node.js runtime. To use this feature, add an attribute `envFile` to your launch configuration and specify the absolute path to the file containing the environment variables: + +```json + //... + "envFile": "${workspaceFolder}/.env", + "env": { "USER": "john doe" } + //... +``` + +Any environment variable specified in the `env` dictionary will override variables loaded from the file. + +Here is an example of an `.env` file: + +``` +USER=doe +PASSWORD=abc123 + +# a comment + +# an empty value: +empty= + +# new lines expanded in quoted strings: +lines="foo\nbar" +``` + +## Attaching to Node.js + +If you want to attach the VS Code debugger to a Node.js program, launch Node.js in VS Code's integrated terminal as follows: + +``` +node --inspect program.js +``` + +or if the program should not start running but must wait for the debugger to attach: + +``` +node --inspect-brk program.js +``` + +Now you have three options for attaching the debugger to your program: + +- have VS Code automatically attach to the program, or +- open a "process picker" that lists all potential candidate processes and let you pick one, or +- create an "attach" configuration that explicitly specifies all configuration options and then press **F5**. + +Let's go through these options in detail: + +### Auto Attach Feature + +If the **Auto Attach** feature is enabled, the Node debugger automatically attaches to Node.js processes that have been launched in debug mode from VS Code's Integrated Terminal. + +To enable the feature, either use the **Toggle Auto Attach** action or, if the Node debugger is already activated, use the **Auto Attach** Status Bar item. + +After enabling **Auto Attach** the debugger should attach to your program within a second: + +![Auto Attach](images/nodejs-debugging/auto-attach.gif) + +Whether or not a process is in "debug mode" is determined by analyzing the program arguments. Currently, we detect the patterns `--inspect`, `--inspect-brk`, `--inspect-port`, `--debug`, `--debug-brk`, `--debug-port` (all optionally followed by a '=' and a port number). + +>**Note:** this feature does not (yet) work for terminal multiplexers like **tmux** (where launched processes are not children of VS Code's integrated terminal). + +### Attach to Node Process action + +The **Attach to Node Process** action opens a Quick Pick menu that lists all potential processes that are available to the Node.js debugger: + +![Node.js Process picker](images/nodejs-debugging/process-picker.png) + +The individual processes listed in the picker show the debug port and the detected protocol in addition to the process id. You should find your Node.js process in that list and after selecting it, the Node.js debugger tries to attach to it. + +In addition to Node.js processes, the picker also shows other programs that were launched with one of the various forms of `--debug` or `--inspect` arguments. This makes it possible to attach to Electron's or VS Code's helper processes. + +### Setting up an "Attach" configuration + +This option requires more work but in contrast to the previous two options it allows you to configure various debug configuration options explicitly. + +The simplest "attach" configuration looks like this: + +```json +{ + "name": "Attach to Process", + "type": "node", + "request": "attach", + "port": 9229 +} +``` + +The port `9229` is the default debug port of the `--inspect` and `--inspect-brk` options. To use a different port (e.g. `12345`), add it to the options like this: `--inspect=12345` and `--inspect-brk=12345` and change the `port` attribute in the launch configuration accordingly. + +If you want to attach to a Node.js process that hasn't been started in debug mode, you can do this by specifying the process ID of the Node.js process as a string: + +```json +{ + "name": "Attach to Process", + "type": "node", + "request": "attach", + "processId": "53426" +} +``` + +Since it is a bit laborious to repeatedly find the process ID and enter it in the launch configuration, Node debug supports a command variable `PickProcess` that binds to the process picker (from above) and that lets you conveniently pick the process from a list of Node.js processes. + +By using the `PickProcess` variable the launch configuration looks like this: + +```json +{ + "name": "Attach to Process", + "type": "node", + "request": "attach", + "processId": "${command:PickProcess}" +} +``` + +## Stop debugging + +Using the **Debug: Stop** action (available in the Debug toolbar or via the **Command Palette**) stops the debug session. + +If the debug session was started in "attach" mode (and the red terminate button in the Debug toolbar shows an superimposed "plug"), pressing **Stop** disconnects the Node.js debugger from the debuggee which then continues execution. + +If the debug session is in "launch" mode, pressing **Stop** does the following: + +1. When pressing **Stop** for the first time, the debuggee is requested to shutdown gracefully by sending a `SIGINT` signal. The debuggee is free to intercept this signal and clean up anything as necessary and then shut down. If there are no breakpoints (or problems) in that shutdown code, the debuggee and the debug session will terminate. + +2. However if the debugger hits a breakpoint in the shutdown code or if the debuggee does not terminate properly by itself, then the debug session will not end. In this case, pressing **Stop** again will force terminate the debuggee and its child processes (`SIGKILL`). + +So if you see that a debug session doesn't end when you press the red **Stop** button, then press the button again to force a shutdown of the debuggee. + +Note that on the Windows operating system, pressing **Stop** always forcibly kills the debuggee and its child processes. + +## Source maps + +The Node.js debugger of VS Code supports JavaScript source maps which help debugging of transpiled languages, for example, TypeScript or minified/uglified JavaScript. With source maps, it is possible to single step through or set breakpoints in the original source. If no source map exists for the original source or if the source map is broken and cannot successfully map between the source and the generated JavaScript, then breakpoints show up as unverified (gray hollow circles). + +Source maps can be generated with two kinds of inlining: + +* _Inlined source maps_: the generated JavaScript file contains the source map as a data URI at the end (instead of referencing the source map through a file URI). +* _Inlined source_: the source map contains the original source (instead of referencing the source through a path). + +VS Code supports both the _inlined source maps_ and the _inlined source_. + +The source map feature is controlled by the `sourceMaps` attribute which defaults to `true`. This means that node debugging always tries to use source maps (if it can find any) and as a consequence, you can even specify a source file (for example, app.ts) with the `program` attribute. + +If you need to disable source maps for some reason, you can set the `sourceMaps` attribute to `false`. + +If the generated (transpiled) JavaScript files do not live next to their source but in a separate directory, you must help the VS Code debugger locating them by setting the `outFiles` attribute. This attribute takes multiple glob patterns for including and excluding files from the set of generated JavaScript files. Whenever you set a breakpoint in the original source, VS Code tries to find the generated JavaScript code in the files specified by `outFiles`. + +Since source maps are not automatically created, you must configure the transpiler you are using to create them. For TypeScript this can be done in the following way: + +``` +tsc --sourceMap --outDir bin app.ts +``` + +This is the corresponding launch configuration for a TypeScript program: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Launch TypeScript", + "type": "node", + "request": "launch", + "program": "app.ts", + "outFiles": [ "${workspaceFolder}/bin/**/*.js" ] + } + ] +} +``` + +### Smart stepping + +With the `smartStep` attribute set to `true` in a launch configuration, VS Code will automatically skip 'uninteresting code' when stepping through code in the debugger. 'Uninteresting code' is code that is generated by a transpiling process but is not covered by a source map so it does not map back to the original source. This code gets in your way when stepping through source code in the debugger because it makes the debugger switch between the original source code and generated code that you are not really interested in. `smartStep` will automatically step through code not covered by a source map until it reaches a location that is covered by a source map again. + +This is especially useful for cases like async/await downcompilation in TypeScript, where the compiler injects helper code that is not covered by a source map. + +Please note that the `smartStep` feature only applies to JavaScript code that was generated from source and therefore has a source map. For JavaScript without sources, the smart stepping option has no effect. + +### JavaScript source map tips + +A common issue when debugging with source maps is that you'll set a breakpoint, and it will turn gray. If you hover the cursor over it, you'll see the message, `"Breakpoint ignored because generated code not found (source map problem?)"`. What now? There are a range of issues that can lead to this. First, a quick explanation of how the Node debug adapter handles source maps. + +When you set a breakpoint in `app.ts`, the debug adapter has to figure out the path to `app.js`, the transpiled version of your TypeScript file, which is what is actually running in Node. But, there is not a straightforward way to figure this out starting from the `.ts` file. Instead, the debug adapter uses the `outFiles` attribute in the `launch.json` to find all the transpiled `.js` files, and parses them for a source map, which contains the locations of its associated `.ts` files. + +When you build your `app.ts` file in TypeScript with source maps enabled, it either produces an `app.js.map` file, or a source map inlined as a base64-encoded string in a comment at the bottom of the `app.js` file. To find the `.ts` files associated with this map, the debug adapter looks at two properties in the source map, `sources`, and `sourceRoot`. `sourceRoot` is optional - if present, it is prepended to each path in `sources`, which is an array of paths. The result is an array of absolute or relative paths to `.ts` files. Relative paths are resolved relative to the source map. + +Finally, the debug adapter searches for the full path of `app.ts` in this resulting list of `.ts` files. If there's a match, it has found the source map file to use when mapping `app.ts` to `app.js`. If there is no match, then it can't bind the breakpoint, and it will turn gray. + +Here are some things to try when your breakpoints turn gray: + +* Do you have `"sourceMaps": false` in your `launch.json`? +* Did you build with source maps enabled? Are there `.js.map` files, or inlined source maps in your `.js` files? +* Did you set the `outFiles` property in your `launch.json`? It should be a glob pattern for an absolute path that matches your `.js` files. +* Try the 'inspector' protocol implementation. It can handle some more of the more complex source map cases. +* Are the `sourceRoot` and `sources` properties in your source map correct? Can they be combined to get the correct path to the `.ts` file? +* Are you using Webpack? By default, it outputs paths with a `webpack:///` prefix, which the debug adapter can't resolve. You can change this in your Webpack configuration with the `devtoolModuleFilenameTemplate` option, or try using the 'inspector' protocol, which provides some extra options for resolving these paths. +* Have you opened the folder in VS Code with the incorrect case? It's possible to open folder `foo/` from the command line like `code FOO` in which case source maps may not be resolved correctly. +* Try searching for help with your particular setup on Stack Overflow or by filing an issue on GitHub. +* Try adding a `debugger` statement. If it breaks into the `.ts` file there, but breakpoints at that spot don't bind, that is useful information to include with a GitHub issue. + +## Remote debugging + +The Node.js debugger supports remote debugging for versions of Node.js >= 4.x. Specify a remote host via the `address` attribute. Here is an example: + +```json +{ + "type": "node", + "request": "attach", + "name": "Attach to remote", + "address": "TCP/IP address of process to be debugged", + "port": "9229" +} +``` + +By default, VS Code will stream the debugged source from the remote Node.js folder to the local VS Code and show it in a read-only editor. You can step through this code, but cannot modify it. If you want VS Code to open the editable source from your workspace instead, you can setup a mapping between the remote and local locations. A `localRoot` and a `remoteRoot` attribute can be used to map paths between a local VS Code project and a (remote) Node.js folder. This works even locally on the same system or across different operating systems. Whenever a code path needs to be converted from the remote Node.js folder to a local VS Code path, the `remoteRoot` path is stripped off the path and replaced by `localRoot`. For the reverse conversion, the `localRoot` path is replaced by the `remoteRoot`. + +```json +{ + "type": "node", + "request": "attach", + "name": "Attach to remote", + "address": "TCP/IP address of process to be debugged", + "port": "9229", + "localRoot": "${workspaceFolder}", + "remoteRoot": "C:\\Users\\John\\project\\server" +} +``` + +Two frequently used applications of remote debugging are: + +* **debugging Node.js in a Docker container:** + + If you are running Node.js inside a [Docker](https://www.docker.com) container, you can use the approach from above to debug Node.js inside the Docker container and map back the remote source to files in your workspace. We have created a "recipe" on [GitHub](https://github.com/Microsoft/vscode-recipes) that walks you through on how to set this up [Node.js in Docker with TypeScript](https://github.com/Microsoft/vscode-recipes/tree/master/Docker-TypeScript). + +* **debugging Node.js in the Linux subsystem on Windows:** + + If you want to run Node.js in the Linux subsystem on Windows (WSL), you can use the approach from above as well. However, to make this even simpler, we've introduced a `useWSL` flag to automatically configure everything so that Node.js runs in the Linux subsystem and source is mapped to files in your workspace. + + Here is the simplest debug configuration for debugging `hello.js` in WSL: + + ```json + { + "type": "node", + "request": "launch", + "name": "Launch in WSL", + "useWSL": true, + "program": "${workspaceFolder}/hello.js" + } + ``` + +## Access Loaded Scripts + +If you need to set a breakpoint in a script that is not part of your workspace and therefore cannot be easily located and opened through normal VS Code file browsing, you can access the loaded scripts via the **LOADED SCRIPTS** view in the debug viewlet: + +![Loaded Scripts Explorer](images/nodejs-debugging/loaded-scripts-explorer.gif) + + Alternatively, you can use the **Debug: Open Loaded Script** action (`kb(extension.node-debug.pickLoadedScript)`) which opens a Quick Pick, where you can filter and select the script to open. + + Scripts are loaded into a read-only editor where you can set breakpoints. These breakpoints are remembered across debug sessions but you only have access to the script content while a debug session is running. + +## Restarting debug sessions automatically when source is edited + +The `restart` attribute of a launch configuration controls whether the Node.js debugger automatically restarts after the debug session has ended. This feature is useful if you use [**nodemon**](https://nodemon.io) to restart Node.js on file changes. Setting the launch configuration attribute `restart` to `true` makes the node debugger automatically try to re-attach to Node.js after Node.js has terminated. + +If you have started your program `server.js` via **nodemon** on the command line like this: + +```bash +nodemon --inspect server.js +``` + +you can attach the VS Code debugger to it with the following launch configuration: + +```json +{ + "name": "Attach to node", + "type": "node", + "request": "attach", + "restart": true, + "port": 9229 +} +``` + +Alternatively you can start your program `server.js` via **nodemon** directly with a launch config and attach the VS Code debugger: + +```json +{ + "name": "Launch server.js via nodemon", + "type": "node", + "request": "launch", + "runtimeExecutable": "nodemon", + "program": "${workspaceFolder}/server.js", + "restart": true, + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen" +} +``` + +>**Tip:** Pressing the **Stop** button stops the debug session and disconnects from Node.js, but **nodemon** (and Node.js) will continue to run. To stop **nodemon**, you will have to kill it from the command line (which is easily possible if you use the `integratedTerminal` as shown above). + +>**Tip:** In case of syntax errors, **nodemon** will not be able to start Node.js successfully until the error has been fixed. In this case, VS Code will continue trying to attach to Node.js but eventually give up (after 10 seconds). To avoid this, you can increase the timeout by adding a `timeout` attribute with a larger value (in milliseconds). + +## Automatically attach debugger to Node.js subprocesses + +The Node debugger has a mechanism that tracks all subprocesses of a debuggee and tries to automatically attach to those processes that are launched in debug mode. This feature simplifies debugging of programs that fork or spawn Node.js processes like programs based on the "cluster" node module: + +![Auto Attach shown with Cluster Example](images/nodejs-debugging/auto-attach-cluster.gif) + +The feature is enabled by setting the launch config attribute `autoAttachChildProcesses` to true: + +```json +{ + "type": "node", + "request": "launch", + "name": "Cluster", + "program": "${workspaceFolder}/cluster.js", + "autoAttachChildProcesses": true +} +``` + +>**Tip:** In order to be able to track the subprocesses, we need the process ID of the parent. For this we require that the main debuggee launched from the launch config is a Node.js process and we use an "evaluate" to find its process ID. + +>**Tip:** Whether a process is in debug mode is guessed by analyzing the program arguments. Currently we detect the patterns `--inspect`, `--inspect-brk`, `--inspect-port`, `--debug`, `--debug-brk`, `--debug-port` (all optionally followed by a `=` and a port number). + +## Restart frame (node) + +The Node debugger supports restarting execution at a stack frame. This can be useful in situations where you have found a problem in your source code and you want to rerun a small portion of the code with modified input values. Stopping and then restarting the full debug session can be very time-consuming. The **Restart Frame** action allows you to re-enter the current function after you have changed variables with the **Set Value** action: + +

+ restart frame +

+ +Note that **Restart Frame** won't unroll any state changes, so it may not always work as expected. + +Make sure to use a Node.js version >= 5.11 since earlier versions do not work in all situations. + +## Breakpoints + +### Function breakpoints + +The Node.js debugger only supports function breakpoints when the "legacy" protocol is used (that is when targeting Node.js < 8.0 versions). In addition, be aware of the following limitations when using function breakpoints: + +- Function breakpoints only work for global, non-native functions. +- Function breakpoints can only be created if the function has been defined (and has been seen by the debugger). + +

+ function breakpoint +

+ +### Breakpoint hit counts + +The 'hit count condition' controls how many times a breakpoint needs to be hit before it will 'break' execution. The hit count syntax supported by the Node.js debugger is either an integer or one of the operators `<`, `<=`, `==`, `>`, `>=`, `%` followed by an integer. + +Some examples: + +- `>10` break always after 10 hits +- `<3` break on the first two hits only +- `10` same as `>=10` +- `%2` break on every other hit + +### Breakpoint validation + +For performance reasons, Node.js parses the functions inside JavaScript files lazily on first access. As a consequence, breakpoints don't work in source code areas that haven't been seen (parsed) by Node.js. + +Since this behavior is not ideal for debugging, VS Code passes the `--nolazy` option to Node.js automatically. This prevents the delayed parsing and ensures that breakpoints can be validated before running the code (so they no longer "jump"). + +Since the `--nolazy` option might increase the start-up time of the debug target significantly, you can easily opt out by passing a `--lazy` as a `runtimeArgs` attribute. + +When doing so you will find that some of your breakpoints don't "stick" to the line requested but instead "jump" for the next possible line in already-parsed code. To avoid confusion, VS Code always shows breakpoints at the location where Node.js thinks the breakpoint is. In the **BREAKPOINTS** section, these breakpoints are shown with an arrow between requested and actual line number: + +![Breakpoints View](images/nodejs-debugging/breakpointsvalidation.png) + +This breakpoint validation occurs when a session starts and the breakpoints are registered with Node.js, or when a session is already running and a new breakpoint is set. In this case, the breakpoint may "jump" to a different location. After Node.js has parsed all the code (e.g. by running through it), breakpoints can be easily re-applied to the requested locations with the **Reapply** button in the **BREAKPOINTS** section header. This should make the breakpoints "jump back" to the requested location. + +![Breakpoint Actions](images/nodejs-debugging/breakpointstoolbar.png) + +## Skipping uninteresting code (node, chrome) + +VS Code Node.js debugging has a feature to avoid source code that you don't want to step through (AKA 'Just My Code'). This feature can be enabled with the `skipFiles` attribute in your launch configuration. `skipFiles` is an array of glob patterns for script paths to skip. + +For example, using: + +```typescript + "skipFiles": [ + "${workspaceFolder}/node_modules/**/*.js", + "${workspaceFolder}/lib/**/*.js" + ] +``` + +all code in the `node_modules` and `lib` folders in your project will be skipped. + +Built-in **core modules** of Node.js can be referred to by the 'magic name' `` in a glob pattern. The following example skips all internal modules: + +```json + "skipFiles": [ + "/**/*.js" + ] +``` + +The exact 'skipping' rules are as follows: + +* If you step into a skipped file, you won't stop there - you will stop on the next executed line that is not in a skipped file. +* If you have set the option to break on thrown exceptions, then you won't break on exceptions thrown from skipped files. +* If you set a breakpoint in a skipped file, you will stop at that breakpoint, and you will be able to step through it until you step out of it, at which point normal skipping behavior will resume. + +Skipped source is shown in a 'dimmed' style in the CALL STACK view: + +![Skipped source is dimmed in call stack view](images/nodejs-debugging/dimmed-callstack.png) + +Hovering over the dimmed entries explains why the stack frame is dimmed. + +A context menu item on the call stack, **Toggle skipping this file** enables you to easily skip a file at runtime without adding it to your launch config. This option only persists for the current debugging session. You can also use it to stop skipping a file that is skipped by the `skipFiles` option in your launch config. + +>**Note:** The `legacy` protocol debugger supports negative glob patterns, but they must **follow** a positive pattern: positive patterns add to the set of skipped files, while negative patterns subtract from that set. + +In the following (`legacy` protocol-only) example all but a 'math' module is skipped: + +```typescript +"skipFiles": [ + "${workspaceFolder}/node_modules/**/*.js", + "!${workspaceFolder}/node_modules/math/**/*.js" +] +``` + +>**Note:** The `legacy` protocol debugger has to emulate the `skipFiles` feature because the _V8 Debugger Protocol_ does not support it natively. This might result in slow stepping performance. + +## Next steps + +In case you didn't already read the Node.js section, take a look at: + +* [Node.js](/docs/nodejs/nodejs-tutorial.md) - End to end Node scenario with a sample application + + + +To see tutorials on the basics of Node.js debugging, check out these videos: + +* [Intro Video - Debugging](/docs/introvideos/debugging.md) - Introductory video showcasing the basics of debugging. +* [Getting started with Node.js debugging](https://www.youtube.com/watch?v=2oFKNL7vYV8) - Learn how to attach to a running Node.js process. + +To learn about VS Code's task running support, go to: + +* [Tasks](/docs/editor/tasks.md) - Running tasks with Gulp, Grunt and Jake. Showing Errors and Warnings + +To write your own debugger extension, visit: + +* [Debugger Extension](/api/extension-guides/debugger-extension.md) - Steps to create a VS Code debug extension starting from a mock sample + +## Common questions + +### Can I debug if I'm using symlinks? + +Yes, if you've created symlinks with `npm link`, you can debug symlink sources by telling the Node.js runtime to honor those symlinks. Use the node.exe `--preserve-symlinks` [switch](https://nodejs.org/api/cli.html#cli_preserve_symlinks) in your launch configuration `runtimeArgs` attribute. `runtimeArgs`, an array of strings, are passed to the debugging session runtime executable, which defaults to node.exe. + +```json +{ + "runtimeArgs": [ + "--preserve-symlinks" + ] +} +``` + +If your main script is inside a symlinked path, then you will also need to add the `"--preserve-symlinks-main"` option. This option is only available in Node 10+. + +### How do I debug ECMAScript modules? + +If you use esm or pass `--experimental-modules` to Node.js in order to use ECMAScript modules, you can pass these options through the `runtimeArgs` attribute of `launch.json`: + +* `"runtimeArgs": ["--experimental-modules"]` - Use the [experimental ECMAScript modules support](https://nodejs.org/api/esm.html) in Node v8.5.0+ +* `"runtimeArgs": ["-r", "esm"]` - Use the [esm ES module loader](https://github.com/standard-things/esm) (Note that `["-r esm"]` without a comma won't work) diff --git a/docs/nodejs/nodejs-deployment.md b/docs/nodejs/nodejs-deployment.md new file mode 100644 index 0000000000000000000000000000000000000000..b93126859998675910cbc254c99133ae9b0aded6 --- /dev/null +++ b/docs/nodejs/nodejs-deployment.md @@ -0,0 +1,36 @@ +--- +Order: 4 +Area: nodejs +TOCTitle: Node.js Deployment +PageTitle: Node.js Deployment with Visual Studio Code +ContentId: 856a4a73-a4b4-4418-b88d-1f65d0ba7824 +MetaDescription: Node.js Deployment to Azure with Visual Studio Code +DateApproved: 3/7/2019 +--- +# Deploy a Node.js Application to Azure + +You can deploy your Node.js applications to [Azure](https://azure.microsoft.com) directly from Visual Studio Code. Using either the [Azure CLI](https://docs.microsoft.com/cli/azure/overview?view=azure-cli-latest) or the [Azure App Service](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) extension, you can have your application running in Azure in minutes. + +![app service](images/nodejs-deployment/azure-app-service-tools.png) + +## Azure tutorials + +The tutorials below will walk you through creating a simple website and deploying it to Azure: + +Tutorial | Description +--- | --- +[Deploy Azure Functions](/tutorials/functions-extension/getting-started) | Build and manage Azure Functions serverless apps directly in VS Code with the Azure Functions extension. +[Deploy using the App Service extension](/tutorials/app-service-extension/getting-started) | Manage Azure resources directly in VS Code with the Azure App Service extension. +[Deploy using Docker](/tutorials/docker-extension/getting-started) | Deploy your website using a Docker container. +[Deploy using the Azure CLI](/tutorials/nodejs-deployment/getting-started) | Create, deploy, and update a website using a terminal and the Azure CLI. +[Deploy a static website](/tutorials/static-website/getting-started) | Create, deploy, and update a static website on Azure Storage. + +## Azure extensions + +There are many other VS Code extensions on the [Marketplace](https://marketplace.visualstudio.com/search?term=azure&target=VSCode&category=All%20categories&sortBy=Relevance) that make it easy to build and host applications on Azure. + +
+ +> **Tip:** Click on an extension tile above to read the description and reviews in the Marketplace. + +There is also a [Node Pack for Azure](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack) extension pack which bundles useful Azure extensions for Node.js developers into a single installation. diff --git a/docs/nodejs/nodejs-tutorial.md b/docs/nodejs/nodejs-tutorial.md new file mode 100644 index 0000000000000000000000000000000000000000..66675f43826fce631a128abc237c100730da8d76 --- /dev/null +++ b/docs/nodejs/nodejs-tutorial.md @@ -0,0 +1,207 @@ +--- +Order: 2 +Area: nodejs +TOCTitle: Node.js Tutorial +ContentId: ED394CD2-D09E-4E3A-96AD-6D3D8337BA9D +PageTitle: Build Node.js Apps with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: The Visual Studio Code editor has great support for writing and debugging Node.js applications. This tutorial takes you from Hello World to a full Express web application. +MetaSocialImage: images/nodejs/runtimes_node.png +--- +# Node.js tutorial in Visual Studio Code + +[Node.js](https://nodejs.org/) is a platform for building fast and scalable server applications using JavaScript. Node.js is the runtime and [npm](https://www.npmjs.com/) is the Package Manager for Node.js modules. + +Visual Studio Code has support for the JavaScript and TypeScript languages out-of-the-box as well as Node.js debugging. However, to run a Node.js application, you will need to install the Node.js runtime on your machine. + +To get started in this walkthrough, [install Node.js for your platform](https://nodejs.org/en/download/). The Node Package Manager is included in the Node.js distribution. You'll need to open a new terminal (command prompt) for the `node` and `npm` command line tools to be on your PATH. + +>**Linux**: There are specific Node.js packages available for the various flavors of Linux. See [Installing Node.js via package manager](https://nodejs.org/en/download/package-manager) to find the Node.js package and installation instructions tailored to your version of Linux. + +>**Tip:** To test that you've got Node.js correctly installed on your computer, open a new terminal and type `node --help` and you should see the usage documentation. + +## Hello World + +Let's get started by creating the simplest Node.js application, "Hello World". + +Create an empty folder called "hello", navigate into and open VS Code: + +```bash +mkdir hello +cd hello +code . +``` + +>**Tip:** You can open files or folders directly from the command line. The period '.' refers to the current folder, therefore VS Code will start and open the `Hello` folder. + +From the File Explorer tool bar, press the New File button: + +![File Explorer New File](images/nodejs/toolbar-new-file.png) + +and name the file `app.js`: + +![File Explorer app.js](images/nodejs/app-js-file-created.png) + +By using the `.js` file extension, VS Code interprets this file as JavaScript and will evaluate the contents with the JavaScript language service. Refer to the VS Code [JavaScript language](/docs/languages/javascript.md) topic to learn more about JavaScript support. + +Create a simple string variable in `app.js` and send the contents of the string to the console: + +```javascript +var msg = 'Hello World'; +console.log(msg); +``` + +Note that when you typed `console.` [IntelliSense](/docs/editor/intellisense.md) on the `console` object was automatically presented to you. + +![console IntelliSense](images/nodejs/consoleintellisense.png) + +Also notice that VS Code knows that `msg` is a string based on the initialization to `'Hello World'`. If you type `msg.` you'll see IntelliSense showing all of the string functions available on `msg`. + +![string IntelliSense](images/nodejs/stringintellisense.png) + +After experimenting with IntelliSense, revert any extra changes from the source code example above and save the file (`kb(workbench.action.files.save)`). + +### Running Hello World + +It's simple to run `app.js` with Node.js. From a terminal, just type: + +```bash +node app.js +``` + +You should see "Hello World" output to the terminal and then Node.js returns. + +### Integrated Terminal + +VS Code has an [integrated terminal](/docs/editor/integrated-terminal.md) which you can use to run shell commands. You can run Node.js directly from there and avoid switching out of VS Code while running command line tools. + +**View** > **Terminal** (`kb(workbench.action.terminal.toggleTerminal)` with the backtick character) will open the integrated terminal and you can run `node app.js` there: + +![integrated terminal](images/nodejs/integrated-terminal.png) + +For this walkthrough, you can use either an external terminal or the VS Code integrated terminal for running the command line tools. + +### Debugging Hello World + +As mentioned in the introduction, VS Code ships with a debugger for Node.js applications. Let's try debugging our simple Hello World application. + +To set a breakpoint in `app.js`, put the editor cursor on the first line and press `kb(editor.debug.action.toggleBreakpoint)` or click in the editor left gutter next to the line numbers. A red circle will appear in the gutter. + +![app.js breakpoint set](images/nodejs/app-js-breakpoint-set.png) + +To start debugging, select the Debug View in the Activity Bar: + +![Debug icon](images/nodejs/debugicon.png) + +You can now click Debug tool bar green arrow or press `kb(workbench.action.debug.start)` to launch and debug "Hello World". Your breakpoint will be hit and you can view and step through the simple application. Notice that VS Code displays a different colored Status Bar to indicate it is in Debug mode and the DEBUG CONSOLE is displayed. + +![hello world debugging](images/nodejs/hello-world-debugging.png) + +Now that you've seen VS Code in action with "Hello World", the next section shows using VS Code with a full-stack Node.js web app. + +>**Note:** We're done with the "Hello World" example so navigate out of that folder before you create an Express app. You can delete the "Hello" folder if you wish as it is not required for the rest of the walkthrough. + +## An Express application + +[Express](https://expressjs.com/) is a very popular application framework for building and running Node.js applications. You can scaffold (create) a new Express application using the Express Generator tool. The Express Generator is shipped as an npm module and installed by using the npm command line tool `npm`. + +>**Tip:** To test that you've got `npm` correctly installed on your computer, type `npm --help` from a terminal and you should see the usage documentation. + +Install the Express Generator by running the following from a terminal: + +```bash +npm install -g express-generator +``` + +The `-g` switch installs the Express Generator globally on your machine so you can run it from anywhere. + +We can now scaffold a new Express application called `myExpressApp` by running: + +```bash +express myExpressApp +``` + +This creates a new folder called `myExpressApp` with the contents of your application. To install all of the application's dependencies (again shipped as npm modules), go to the new folder and execute `npm install`: + +```bash +cd myExpressApp +npm install +``` + +At this point, we should test that our application runs. The generated Express application has a `package.json` file which includes a `start` script to run `node ./bin/www`. This will start the Node.js application running. + +From a terminal in the Express application folder, run: + +```bash +npm start +``` + +>**Tip:** You can enable an explorer for the npm scripts in your workspace using the `npm.enableScriptExplorer` setting. + +The Node.js web server will start and you can browse to [http://localhost:3000](http://localhost:3000) to see the running application. + +![Your first Node Express App](images/nodejs/express.png) + +## Great code editing + +Close the browser and from a terminal in the `myExpressApp` folder, stop the Node.js server by pressing `kbstyle(CTRL+C)`. + +Now launch VS Code: + +```bash +code . +``` + +>**Note:** If you've been using the VS Code integrated terminal to install the Express generator and scaffold the app, you can open the `myExpressApp` folder from your running VS Code instance with the **File** > **Open Folder** command. + +The [Node.js](https://nodejs.org/api/) and [Express](https://expressjs.com/api.html) documentation does a great job explaining how to build rich applications using the platform and framework. Visual Studio Code will make you more productive developing these types of applications by providing great code editing and navigation experiences. + +Open the file `app.js` and hover over the Node.js global object `__dirname`. Notice how VS Code understands that `__dirname` is a string. Even more interesting, you can get full IntelliSense against the Node.js framework. For example, you can require `http` and get full IntelliSense against the `http` class as you type in Visual Studio Code. + +![http IntelliSense](images/nodejs/intellisense.png) + +VS Code uses TypeScript type declaration (typings) files (for example `node.d.ts`) to provide metadata to VS Code about the JavaScript based frameworks you are consuming in your application. Type declaration files are written in TypeScript so they can express the data types of parameters and functions, allowing VS Code to provide a rich IntelliSense experience. Thanks to a feature called `Automatic Type Acquisition`, you do not have to worry about downloading these type declaration files, VS Code will install them automatically for you. + +You can also write code that references modules in other files. For example, in `app.js` we require the `./routes/index` module, which exports an `Express.Router` class. If you bring up IntelliSense on `index`, you can see the shape of the `Router` class. + +![Express.Router IntelliSense](images/nodejs/moduleintellisense.png) + +## Debug your Express app + +You will need to create a debugger configuration file `launch.json` for your Express application. Click on the Debug icon in the **Activity Bar** and then the Configure gear icon at the top of the Debug view to create a default `launch.json` file. Select the **Node.js** environment by ensuring that the `type` property in `configurations` is set to `"node"`. When the file is first created, VS Code will look in `package.json` for a `start` script and will use that value as the `program` (which in this case is `"${workspaceFolder}\\bin\\www`) for the **Launch Program** configuration. + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${workspaceFolder}\\bin\\www" + } + ] +} +``` + +Save the new file and make sure **Launch Program** is selected in the configuration drop-down at the top of the Debug view. Open `app.js` and set a breakpoint near the top of the file where the Express app object is created by clicking in the gutter to the left of the line number. Press `kb(workbench.action.debug.start)` to start debugging the application. VS Code will start the server in a new terminal and hit the breakpoint we set. From there you can inspect variables, create watches, and step through your code. + +![Debug session](images/nodejs/debugsession.png) + +## Deploy your application + +If you'd like to learn how to deploy your web application, check out the [Deploying Applications to Azure](/docs/azure/deployment.md) tutorials where we show how to run your website in Azure. + +--- + +## Next steps + +There is much more to explore with Visual Studio Code, please try the following topics: + +* [Settings](/docs/getstarted/settings.md) - Learn how to customize VS Code for how you like to work. +* [Debugging](/docs/editor/debugging.md) - This is where VS Code really shines. +* [Video: Getting started with Node.js debugging](https://www.youtube.com/watch?v=2oFKNL7vYV8) - Learn how to attach to a running Node.js process. +* [Node.js debugging](/docs/nodejs/nodejs-debugging.md) - Learn more about VS Code's built-in Node.js debugging. +* [Debugging recipes](/docs/nodejs/debugging-recipes.md) - Examples for scenarios like client-side and container debugging. +* [Tasks](/docs/editor/tasks.md) - Running tasks with Gulp, Grunt and Jake. Showing Errors and Warnings. + diff --git a/docs/nodejs/reactjs-tutorial.md b/docs/nodejs/reactjs-tutorial.md new file mode 100644 index 0000000000000000000000000000000000000000..bf2eb7e02d5899d3ac4d37de59fe9d4afecc18bc --- /dev/null +++ b/docs/nodejs/reactjs-tutorial.md @@ -0,0 +1,271 @@ +--- +Order: 5 +Area: nodejs +TOCTitle: React Tutorial +ContentId: 2dd2eeff-2eb3-4a0c-a59d-ea9a0b10c468 +PageTitle: React JavaScript Tutorial in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: React JavaScript tutorial showing IntelliSense, debugging, and code navigation support in the Visual Studio Code editor. +MetaSocialImage: /assets/images/nodejs_javascript_vscode.png +--- +# Using React in Visual Studio Code + +[React](https://facebook.github.io/react/) is a popular JavaScript library developed by Facebook for building web application user interfaces. The Visual Studio Code editor supports React.js IntelliSense and code navigation out of the box. + +![welcome to react](images/reactjs/welcome-to-react.png) + +## Welcome to React + +We'll be using the `create-react-app` [generator](https://facebook.github.io/react/docs/installation.html#creating-a-new-application) for this tutorial. To install and use the generator as well as run the React application server, you'll need [Node.js](https://nodejs.org/) JavaScript runtime and [npm](https://www.npmjs.com/) (Node.js package manager) installed. npm is included with Node.js which you can download and install from [here](https://nodejs.org/en/download/). + +>**Tip**: To test that you have Node.js and npm correctly installed on your machine, you can type `node --version` and `npm --version` in a terminal or command prompt. + +To install the `create-react-app` generator, in a terminal or command prompt type: + +```bash +npm install -g create-react-app +``` + +This may take a few minutes to install. You can now create a new React application by typing: + +```bash +create-react-app my-app +``` + +where `my-app` is the name of the folder for your application. This may take a few minutes to create the React application and install its dependencies. + +Let's quickly run our React application by navigating to the new folder and typing `npm start` to start the web server and open the application in a browser: + +```bash +cd my-app +npm start +``` + +You should see "Welcome to React" on [http://localhost:3000](http://localhost:3000) in your browser. We'll leave the web server running while we look at the application with VS Code. + +To open your React application in VS Code, open another terminal or command prompt window, navigate to the `my-app` folder and type `code .`: + +```bash +cd my-app +code . +``` + +### Markdown preview + +In the File Explorer, one file you'll see is the application `README.md` Markdown file. This has lots of great information about the application and React in general. A nice way to review the README is by using the VS Code [Markdown Preview](/docs/languages/markdown.md#markdown-preview). You can open the preview in either the current editor group (**Markdown: Open Preview** `kb(markdown.showPreview)`) or in a new editor group to the side (**Markdown: Open Preview to the Side** `kb(markdown.showPreviewToSide)`). You'll get nice formatting, hyperlink navigation to headers, and syntax highlighting in code blocks. + +![README markdown preview](images/reactjs/markdown-preview.png) + +### Syntax highlighting and bracket matching + +Now expand the `src` folder and select the `index.js` file. You'll notice that VS Code has syntax highlighting for the various source code elements and, if you put the cursor on a parentheses, the matching bracket is also selected. + +![react bracket matching](images/reactjs/bracket-matching.png) + +### IntelliSense + +As you start typing in `index.js`, you'll see smart suggestions or completions. + +![react suggestions](images/reactjs/suggestions.png) + +After you select a suggestion and type `.`, you see the types and methods on the object through [IntelliSense](/docs/editor/intellisense.md). + +![react intellisense](images/reactjs/intellisense.png) + +VS Code uses the TypeScript language service for its JavaScript code intelligence and it has a feature called [Automatic Type Acquisition](/docs/languages/javascript.md#automatic-type-acquisition) (ATA). ATA pulls down the npm Type Declaration files (`*.d.ts`) for the npm modules referenced in the `package.json`. + +If you select a method, you'll also get parameter help: + +![react parameter help](images/reactjs/parameter-help.png) + +### Go to Definition, Peek definition + +Through the TypeScript language service, VS Code can also provide type definition information in the editor through **Go to Definition** (`kb(editor.action.revealDefinition)`) or **Peek Definition** (`kb(editor.action.peekDefinition)`). Put the cursor over the `App`, right click and select **Peek Definition**. A [Peek window](/docs/editor/editingevolved.md#peek) will open showing the `App` definition from `App.js`. + +![react peek definition](images/reactjs/peek-definition.png) + +Press `kbstyle(Escape)` to close the Peek window. + +## Hello World! + +Let's update the sample application to "Hello World!". Add the link to declare a new H1 header and replace the `` tag in `ReactDOM.render` with `element`. + +```js +import React from 'react'; +import ReactDOM from 'react-dom'; +import App from './App'; +import registerServiceWorker from './registerServiceWorker'; +import './index.css'; + +var element = React.createElement('h1', { className: 'greeting' }, 'Hello, world!'); +ReactDOM.render(element, document.getElementById('root')); +registerServiceWorker(); +``` + +Once you save the `index.js` file, the running instance of the server will update the web page and you'll see "Hello World!". + +>**Tip**: VS Code supports Auto Save, which by default saves your files after a delay. Check the **Auto Save** option in the **File** menu to turn on Auto Save or directly configure the `files.autoSave` user [setting](/docs/getstarted/settings.md). + +![hello world](images/reactjs/hello-world.png) + +## Debugging React + +To debug the client side React code, we'll need to install the [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) extension. + +>Note: This tutorial assumes you have the Chrome browser installed. Microsoft also publishes a version of this extension for their [Edge](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-edge) browser. + +Open the Extensions view (`kb(workbench.view.extensions)`) and type 'chrome` in the search box. You'll see several extensions which reference Chrome. + +![debugger for chrome](images/reactjs/debugger-for-chrome.png) + +Press the **Install** button for **Debugger for Chrome**. The button will change to **Installing** then, after completing the installation, it will change to **Reload**. Press **Reload** to restart VS Code and activate the extension. + +### Set a breakpoint + +To set a breakpoint in `index.js`, click on the gutter to the left of the line numbers. This will set a breakpoint which will be visible as a red circle. + +![set a breakpoint](images/reactjs/breakpoint.png) + +### Configure the Chrome debugger + +We need to initially configure the [debugger](/docs/editor/debugging.md). To do so, go to the Debug view (`kb(workbench.view.debug)`) and click on the gear button to create a `launch.json` debugger configuration file. Choose **Chrome** from the **Select Environment** drop-down list. This will create a `launch.json` file in a new `.vscode` folder in your project which includes a configuration to launch the website. + +We need to make one change for our example: change the port of the `url` from `8080` to `3000`. Your `launch.json` should look like this: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "chrome", + "request": "launch", + "name": "Launch Chrome against localhost", + "url": "http://localhost:3000", + "webRoot": "${workspaceFolder}" + } + ] +} +``` + +Ensure that your development server is running ("npm start"). Then press `kb(workbench.action.debug.start)` or the green arrow to launch the debugger and open a new browser instance. The source code where the breakpoint is set runs on startup before the debugger was attached so we won't hit the breakpoint until we refresh the web page. Refresh the page and you should hit your breakpoint. + +![hit breakpoint](images/reactjs/hit-breakpoint.png) + +You can step through your source code (`kb(workbench.action.debug.stepOver)`), inspect variables such as `element`, and see the call stack of the client side React application. + +![debug variable](images/reactjs/debug-variable.png) + +The **Debugger for Chrome** extension README has lots of information on other configurations, working with sourcemaps, and troubleshooting. You can review it directly within VS Code from the **Extensions** view by clicking on the extension item and opening the **Details** view. + +![debugger for chrome readme](images/reactjs/chrome-debugger-readme.png) + +### Live editing and debugging + +If you are using [webpack](https://webpack.js.org/) together with your React app, you can have a more efficient workflow by taking advantage of webpack's HMR mechanism which enables you to have live editing and debugging directly from VS Code. You can learn more in this [Live edit and debug your React apps directly from VS Code](https://medium.com/@auchenberg/live-edit-and-debug-your-react-apps-directly-from-vs-code-without-leaving-the-editor-3da489ed905f) blog post. + +## Linting + +Linters analyze your source code and can warn you about potential problems before you run your application. The JavaScript language services included with VS Code has syntax error checking support by default which you can see in action in the **Problems** panel (**View** > **Problems** `kb(workbench.actions.view.problems)`). + +Try making a small error in your React source code and you'll see a red squiggle and an error in the **Problems** panel. + +![javascript error](images/reactjs/js-error.png) + +Linters can provide more sophisticated analysis, enforcing coding conventions and detecting anti-patterns. A popular JavaScript linter is [ESLint](https://eslint.org/). ESLint, when combined with the ESLint VS Code [extension](https://marketplace.visualstudio.com/items/dbaeumer.vscode-eslint), provides a great in-product linting experience. + +First, install the ESLint command line tool: + +```bash +npm install -g eslint +``` + +Then install the ESLint extension by going to the **Extensions** view and typing 'eslint'. + +![ESLint extension](images/reactjs/eslint-extension.png) + +Once the ESLint extension is installed and VS Code reloaded, you'll want to create an ESLint configuration file `.eslintrc.json`. You can create one using the extension's **ESLint: Create ESLint configuration** command from the **Command Palette** (`kb(workbench.action.showCommands)`). + +![create eslintrc](images/reactjs/create-eslintrc.png) + +The command will create a `.eslintrc.json` file in your project root: + +```json +{ + "env": { + "browser": true, + "commonjs": true, + "es6": true, + "node": true + }, + "parserOptions": { + "ecmaFeatures": { + "jsx": true + }, + "sourceType": "module" + }, + "rules": { + "no-const-assign": "warn", + "no-this-before-super": "warn", + "no-undef": "warn", + "no-unreachable": "warn", + "no-unused-vars": "warn", + "constructor-super": "warn", + "valid-typeof": "warn" + } +} +``` + +ESLint will now analyze open files and shows a warning in `index.js` about 'App' being defined but never used. + + ![App is unused](images/reactjs/app-is-unused.png) + + You can modify the ESLint [rules](https://eslint.org/docs/rules/) and the ESLint extension provides IntelliSense in `.eslintrc.json`. + +![eslintrc IntelliSense](images/reactjs/eslintrc-intellisense.png) + +Let's add an error rule for extra semi-colons: + +```json + "rules": { + "no-const-assign": "warn", + "no-this-before-super": "warn", + "no-undef": "warn", + "no-unreachable": "warn", + "no-unused-vars": "warn", + "constructor-super": "warn", + "valid-typeof": "warn", + "no-extra-semi":"error" + } +``` + +Now when you mistakenly have multiple semicolons on a line, you'll see an error (red squiggle) in the editor and error entry in the **Problems** panel. + +![extra semicolon error](images/reactjs/extra-semi-error.png) + +## Popular Starter Kits + +In this tutorial, we used the `create-react-app` generator to create a simple React application. There are lots of great samples and starter kits available to help build your first React application. + +### VS Code React Sample + +This is a [sample](https://github.com/Microsoft/vscode-react-sample) React application used for a [demo](https://channel9.msdn.com/events/Build/2017/T6078) at this year's //Build conference. The sample creates a simple TODO application and includes the source code for a Node.js [Express](https://expressjs.com/) server. It also shows how to use the [Babel](https://babeljs.io) ES6 transpiler and then use [webpack](https://webpack.js.org/) to bundle the site assets. + +### MERN Starter + +If you'd like to see a full MERN (MongoDB, Express, React, Node.js) stack example, look at the [MERN Starter](http://mern.io/). You'll need to install and start [MongoDB](https://docs.mongodb.com/v3.0/installation/) but you'll quickly have a MERN application running. There is helpful VS Code-specific documentation at [vscode-recipes](https://github.com/Microsoft/vscode-recipes/tree/master/MERN-Starter) which details setting up Node.js server debugging. VS Code also has great [MongoDB support](/docs/azure/mongodb.md) through the [Azure Cosmos DB](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb) extension. + +### TypeScript React + +If you're curious about TypeScript and React, you can also create a TypeScript version of the `create-react-app` application. See the details at [TypeScript-React-Starter](https://github.com/Microsoft/TypeScript-React-Starter) on the [TypeScript Quick Start](https://www.typescriptlang.org/samples/index.html) site. + +### Angular + +[Angular](https://angular.io/) is another popular web framework. If you'd like to see an example of Angular working with VS Code, check out the [Chrome Debugging with Angular CLI](https://github.com/Microsoft/vscode-recipes/tree/master/Angular-CLI) recipe. It will walk you through creating an Angular application and configuring the `launch.json` file for the [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) extension. + +## Common questions + +### Can I get IntelliSense within declarative JSX? + +Yes. For example, if you open the `create-react-app` project's `App.js` file, you can see IntelliSense within the React JSX in the `render()` method. + +![JSX IntelliSense](images/reactjs/jsx-intellisense.png) diff --git a/docs/nodejs/vuejs-tutorial.md b/docs/nodejs/vuejs-tutorial.md new file mode 100644 index 0000000000000000000000000000000000000000..1db583e4f0f70a4ab29543f7446a0ab7922925b9 --- /dev/null +++ b/docs/nodejs/vuejs-tutorial.md @@ -0,0 +1,141 @@ +--- +Order: 7 +Area: nodejs +TOCTitle: Vue Tutorial +ContentId: 85ce0bcc-d2b8-4b7c-b744-5eddce9a8d00 +PageTitle: Vue JavaScript Tutorial in Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Vue JavaScript tutorial showing IntelliSense, debugging, and code navigation support in the Visual Studio Code editor. +--- +# Using Vue in Visual Studio Code + +[Vue.js](https://vuejs.org/) is a popular JavaScript library for building web application user interfaces and Visual Studio Code has built-in support for the Vue.js building blocks of [HTML](/docs/languages/html.md), [CSS](/docs/languages/css.md), and [JavaScript](/docs/languages/javascript.md). For a richer Vue.js development environment, you can install the [Vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur) extension which supports Vue.js IntelliSense, code snippets, formatting, and more. + +--- + +![welcome to Vue](images/vuejs/welcome-to-vue.png) + +--- + +## Welcome to Vue + +We'll be using the [Vue CLI](https://cli.vuejs.org/) for this tutorial. If you are new to the Vue.js framework, you can find great documentation and tutorials on the [vuejs.org](https://vuejs.org) website. + +To install and use the Vue CLI as well as run the Vue application server, you'll need the [Node.js](https://nodejs.org/) JavaScript runtime and [npm](https://www.npmjs.com/) (the Node.js package manager) installed. npm is included with Node.js which you can install from [here](https://nodejs.org/en/download/). + +>**Tip**: To test that you have Node.js and npm correctly installed on your machine, you can type `node --version` and `npm --version`. + +To install the `vue/cli` , in a terminal or command prompt type: + +```bash +npm install -g @vue/cli +``` + +This may take a few minutes to install. You can now create a new Vue.js application by typing: + +```bash +vue create my-app +``` + +where `my-app` is the name of the folder for your application. You will be prompted to select a preset and you can keep the default `(babel, eslint)`, which will use [Babel](https://babeljs.io) to transpile the JavaScript to browser compatible ES5 and install the [ESLint](http://eslint.org/) linter to detect coding errors. It may take a few minutes to create the Vue application and install its dependencies. + +Let's quickly run our Vue application by navigating to the new folder and typing `npm run serve` to start the web server and open the application in a browser: + +```bash +cd my-app +npm run serve +``` + +You should see "Welcome to your Vue.js App" on [http://localhost:8080](http://localhost:8080) in your browser. You can press `kbstyle(Ctrl+C)` to stop the `vue-cli-service` server. + +To open your Vue application in VS Code, from a terminal (or command prompt), navigate to the `my-app` folder and type `code .`: + +```bash +cd my-app +code . +``` + +VS Code will launch and display your Vue application in the File Explorer. + +## Vetur extension + +Now expand the `src` folder and select the `App.vue` file. You'll notice that VS Code doesn't show any syntax highlighting and it treats the file as **Plain Text** as you can see in the lower right Status Bar. You'll also see a notification recommending the [Vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur) extension for the `.vue` file type. + +![vetur extension recommendation](images/vuejs/vetur-extension-recommendation.png) + +The Vetur extension supplies Vue.js language features (syntax highlighting, IntelliSense, snippets, formatting) to VS Code. + +![vetur extension](images/vuejs/vetur-extension.png) + +From the notification, press **Install** to download and install the Vetur extension. You should see the Vetur extension **Installing** in the Extensions view. Once the installation is complete (may take several minutes), you will be prompted to **Reload** VS Code with the extension enabled. + +Now you should see that `.vue` is a recognized file type for the Vue language and you have language features such as syntax highlighting, bracket matching, and hover descriptions. + +![vue language features](images/vuejs/vue-language-features.png) + +## IntelliSense + +As you start typing in `App.vue`, you'll see smart suggestions or completions both for HTML and CSS but also for Vue.js specific items like declarations (`v-bind`, `v-for`) in the Vue `template` section: + +![Vue.js suggestions](images/vuejs/suggestions.png) + +and Vue properties (`methods`, `computed`) in the `scripts` section: + +![Vue.js JavaScript suggestions](images/vuejs/javascript-suggestions.png) + +### Go to Definition, Peek definition + +VS Code through the Vue extension language service can also provide type definition information in the editor through **Go to Definition** (`kb(editor.action.revealDefinition)`) or **Peek Definition** (`kb(editor.action.peekDefinition)`). Put the cursor over the `App`, right click and select **Peek Definition**. A [Peek window](/docs/editor/editingevolved.md#peek) will open showing the `App` definition from `App.js`. + +![Vue.js peek definition](images/vuejs/peek-definition.png) + +Press `kbstyle(Escape)` to close the Peek window. + +## Hello World! + +Let's update the sample application to "Hello World!". In `App.vue` replace the HelloWorld component `msg` custom attribute text with "Hello World!". + +```html + +``` + +Once you save the `App.vue` file (`kb(workbench.action.files.save)`), restart the server with `npm run serve` and you'll see "Hello World!". Leave the server running while we go on to learn about Vue.js client side debugging. + +>**Tip**: VS Code supports Auto Save, which by default saves your files after a delay. Check the **Auto Save** option in the **File** menu to turn on Auto Save or directly configure the `files.autoSave` user [setting](/docs/getstarted/settings.md). + +--- + +![hello world](images/vuejs/hello-world.png) + +--- + +## Linting + +Linters analyze your source code and can warn you about potential problems before you run your application. The Vue ESLint plugin ([eslint-plugin-vue](https://www.npmjs.com/package/eslint-plugin-vue)) checks for Vue.js specific syntax errors which are shown in the editor as red squigglies and are also displayed in the **Problems** panel (**View** > **Problems** `kb(workbench.actions.view.problems)`). + +Below you can see an error when the Vue linter detects more than one root element in a template: + +![Vue linting](images/vuejs/vue-linting.png) + +## Debugging + +You can debug client side Vue.js code with the [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) extension. You can learn more from the [Vue.js debugging in Chrome and VS Code](https://github.com/Microsoft/vscode-recipes/tree/master/vuejs-cli) recipe on the VS Code debugging [recipes](https://github.com/Microsoft/vscode-recipes) site. + +>Note: There are currently issues with the sourcemaps generated by vue-cli, which cause issues with the debugging experience in VS Code. See https://github.com/vuejs/vue-loader/issues/1163. + +Another popular tool for debugging Vue.js is the [vue-devtools](https://github.com/vuejs/vue-devtools) plug-in. + +## Other extensions + +Vetur is only one of many Vue.js extensions available for VS Code. You can search in the Extensions view (`kb(workbench.view.extensions)`) by typing 'vue'. + +![Vue.js extensions](images/vuejs/vue-extensions.png) + +There are also Extension Packs which bundle extensions that other people have found useful for Vue.js development. + +![Vue.js extension pack](images/vuejs/vue-extension-pack.png) diff --git a/docs/nodejs/working-with-javascript.md b/docs/nodejs/working-with-javascript.md new file mode 100644 index 0000000000000000000000000000000000000000..85fdfd48f749e98d3cd61bcba27d33622459e3b9 --- /dev/null +++ b/docs/nodejs/working-with-javascript.md @@ -0,0 +1,302 @@ +--- +Order: 1 +Area: nodejs +TOCTitle: Working with JavaScript +PageTitle: Working with JavaScript in Visual Studio Code +ContentId: 3e5af2a6-7669-4b5d-b19f-78077af14fda +DateApproved: 3/7/2019 +MetaDescription: Working with JavaScript in Visual Studio Code +--- +# Working with JavaScript + +This topic describes some of the advanced JavaScript features supported by Visual Studio Code. Using the TypeScript language service, VS Code can provide smart completions (IntelliSense) as well as type checking for JavaScript. + +## IntelliSense + +Visual Studio Code's JavaScript [IntelliSense](/docs/editor/intellisense.md) provides intelligent code completion, parameter info, references search, and many other advanced language features. Our JavaScript IntelliSense is powered by the [JavaScript language service](https://github.com/Microsoft/TypeScript/wiki/JavaScript-Language-Service-in-Visual-Studio) developed by the TypeScript team. While IntelliSense should just work for most JavaScript projects without any configuration, you can make IntelliSense even more useful with [JS Docs](/docs/languages/javascript#js-doc-support) or by configuring a `jsconfig.json` project. + +For the details of how JavaScript IntelliSense works, including being based on type inference, JSDoc annotations, TypeScript declarations, and mixing JavaScript and TypeScript projects, see the [JavaScript language service documentation](https://github.com/Microsoft/TypeScript/wiki/JavaScript-Language-Service-in-Visual-Studio). + +When type inference does not provide the desired information, type information may be provided explicitly with JSDoc annotations. This document describes the [JSDoc annotations](https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-in-JavaScript) currently supported. + +In addition to objects, methods, and properties, the JavaScript IntelliSense window also provides basic word completion for the symbols in your file. + +### Typings and Automatic Type Acquisition + +IntelliSense for JavaScript libraries and frameworks is powered by TypeScript type declaration (typings) files. Type declaration files are written in TypeScript so they can express the data types of parameters and functions, allowing VS Code to provide a rich IntelliSense experience in a performant manner. + +Many popular libraries ship with typings files so you get IntelliSense for them automatically. For libraries that do not include typings, VS Code's `Automatic Type Acquisition` will automatically install community maintained typings file for you. + +Automatic type acquisition requires [npmjs](https://www.npmjs.com), the Node.js package manager, which is included with the [Node.js](https://nodejs.org) runtime. In this image you can see IntelliSense, including the method signature, parameter info, and the method's documentation for the popular [lodash](https://lodash.com/) library. + +![lodash typings](images/working-with-javascript/lodash-typings.png) + +Type declaration files are automatically downloaded and managed by Visual Studio Code for packages listed in your project's `package.json` or that you import into a JavaScript file. + +```json + "dependencies": { + "lodash": "^4.17.0" + } +``` + +You can alternately explicitly list packages to acquire type declaration files for in a [`jsconfig.json`](#_javascript-projects-jsconfigjson). + +```json + "typeAcquisition": { + "include": [ + "jquery" + ] + } +``` + +Most common JavaScript libraries ship with declaration files or have type declaration files available. You can search for a library's type declaration file package using the [TypeSearch](https://microsoft.github.io/TypeSearch) site. + +### Fixing npm not installed warning for Automatic Type Acquisition + +[Automatic Type Acquisition](#automatic-type-acquisition) uses [npm](https://www.npmjs.com), the Node.js package manager, to install and manage Type Declaration (typings) files. To ensure that Automatic Type Acquisition works properly, first ensure that you have npm installed on your machine. + +Run `npm --version` from a terminal or command prompt to quickly check that npm is installed and available. + +npm is installed with the Node.js runtime, which is available for download from [Nodejs.org](https://nodejs.org). Install the current LTS (Long Term Support) version and the npm executable will be added by default to your system path. + +If you have npm installed but still see a warning message, you can explicitly tell VS Code where npm is installed with the `typescript.npm` [setting](/docs/getstarted/settings.md). This should be set to the full path of the npm executable on your machine, and this does not have to match the version of npm you are using to manage packages in your workspace. `typescript.npm` requires TypeScript 2.3.4+. + +For example, on Windows, you would add a path like this to your `settings.json` file: + +```json + "typescript.npm": "C:\\Program Files\\nodejs\\npm.cmd" +``` + +## JavaScript projects (jsconfig.json) + +The presence of a [jsconfig.json](/docs/languages/jsconfig.md) file in a directory indicates that the directory is the root of a JavaScript project. `jsconfig.json` specifies the root files and the options for the language features provided by the [JavaScript language service](https://github.com/Microsoft/TypeScript/wiki/JavaScript-Language-Service-in-Visual-Studio). For common setups, a `jsconfig.json` file is not required, however, there are situations when you will want to add a `jsconfig.json`. + +- Not all files should be in your JavaScript project (for example, you want to exclude some files from showing IntelliSense). This situation is common with front-end and back-end code. +- Your workspace contains more than one project context. In this situation, you should add a `jsconfig.json` file at the root folder for each project. +- You are using the TypeScript compiler to down-level compile JavaScript source code. + +### Location of jsconfig.json + +To define our code as a JavaScript project, create `jsconfig.json` at the root of your JavaScript code as shown below. A JavaScript project is the source files of the project and should not include the derived or packaged files (such as a `dist` directory). + +![jsconfig setup](images/working-with-javascript/jsconfig_setup.png) + +In more complex projects, you may have more than one `jsconfig.json` file defined inside a workspace. You will want to do this so that the source code in one project does not appear in the IntelliSense of another project. + +Illustrated below is a project with a `client` and `server` folder, showing two separate JavaScript projects: + +![multiple jsconfigs](images/working-with-javascript/complex_jsconfig_setup.png) + +### Writing jsconfig.json + +Below is a simple template for `jsconfig.json` file, which defines the JavaScript `target` to be `ES6` and the `exclude` attribute excludes the `node_modules` folder. You can copy and paste this code into your `jsconfig.json` file. + +```json +{ + "compilerOptions": { + "target": "ES6" + }, + "exclude": [ + "node_modules", + "**/node_modules/*" + ] +} +``` + +The `exclude` attribute tells the language service which files are and are not part of your source code. If IntelliSense is slow, add folders to your `exclude` list (VS Code will prompt you to do this if it detects slow completions). You will want to `exclude` files generated by a build process (such as a `dist` directory). These files will cause suggestions to show up twice and will slow down IntelliSense. + +You can explicitly set the files in your project using the `include` attribute. If no `include` attribute is present, then this defaults to including all files in the containing directory and subdirectories. When a `include` attribute is specified, only those files are included. + +Here is an example with an explicit `include` attribute: + +```json +{ + "compilerOptions": { + "target": "ES6" + }, + "include": [ + "src/**/*" + ] +} +``` + +The best practice, and least error prone route, is to use the `include` attribute with a single `src` folder. Note that file paths in `exclude` and `include` are relative to the location of `jsconfig.json`. + +See [here](/docs/languages/jsconfig.md) for the full documentation of `jsconfig.json`. + +### Migrating to TypeScript + +It is possible to have mixed TypeScript and JavaScript projects. To start migrating to TypeScript, rename your `jsconfig.json` file to `tsconfig.json` and set the `allowJs` property to `true`. For more information, see [Migrating from JavaScript](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html). + +> **Note:** `jsconfig.json` is the same as a `tsconfig.json` file, only with `allowJs` set to true. See [the documentation for `tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) here to see other available options. + +## Type checking JavaScript + +VS Code allows you to leverage some of TypeScript's advanced type checking and error reporting functionality in regular JavaScript files. This is a great way to catch common programming mistakes. These type checks also enable some exciting [Quick Fixes]() for JavaScript, including **Add missing import** and **Add missing property**. + +![Using type checking and Quick Fixes in a JavaScript file](images/working-with-javascript/checkjs-example.gif) + +TypeScript can infer types in `.js` files same as in `.ts` files. When types cannot be inferred, they can be specified using JSDoc comments. You can read more about how TypeScript uses JSDocs for JavaScript type checking [here](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html). + +Type checking of JavaScript is optional and opt-in. Existing JavaScript validation tools such as ESLint can be used alongside the new built-in type checking functionality. + +You can get started with type checking a few different ways depending on your needs. + +**Per file** + +The easiest way to enable type checking in a JavaScript file is by adding `// @ts-check` to the top of a file. + +```js +// @ts-check +let itsAsEasyAs = 'abc' +itsAsEasyAs = 123 // Error: Type '123' is not assignable to type 'string' +``` + +Using `// @ts-check` is a good approach if you just want to try type checking in a few files but not yet enable it for an entire codebase. + +**Using a setting** + +To enable type checking for all JavaScript files without changing any code, just add `"javascript.implicitProjectConfig.checkJs": true` to your workspace or user settings. This enables type checking for any JavaScript file that is not part of a `jsconfig.json` or `tsconfig.json` project. + +You can opt individual files out of type checking with a `// @ts-nocheck` comment at the top of the file: + +```js +// @ts-nocheck +let easy = 'abc' +easy = 123 // no error +``` + +You can also disable individual errors in a JavaScript file using a `// @ts-ignore` comment on the line before the error: + +```js +let easy = 'abc' +// @ts-ignore +easy = 123 // no error +``` + +**Using jsconfig or tsconfig** + +To enable type checking for JavaScript files that are part of a `jsconfig.json` or `tsconfig.json`, add `"checkJs": true` to the project's compiler options: + +`jsconfig.json`: + +```json +{ + "compilerOptions": { + "checkJs": true + }, + "exclude": [ + "node_modules", + "**/node_modules/*" + ] +} +``` + +`tsconfig.json`: + +```json +{ + "compilerOptions": { + "allowJs": true, + "checkJs": true + }, + "exclude": [ + "node_modules", + "**/node_modules/*" + ] +} +``` + +This enables type checking for all JavaScript files in the project. You can use `// @ts-nocheck` to disable type checking per file. + +JavaScript type checking requires TypeScript 2.3. If you are unsure what version of TypeScript is currently active in your workspace, run the **TypeScript: Select TypeScript Version** command to check. You must have a `.js/.ts` file open in the editor to run this command. If you open a TypeScript file, the version appears in the lower right corner. + +### Global variables and type checking + +Let's say that you are working in legacy JavaScript code that uses global variables or non-standard DOM APIs: + +```ts +window.onload = function() { + if (window.webkitNotifications.requestPermission() === CAN_NOTIFY) { + window.webkitNotifications.createNotification(null, 'Woof!', '🐶').show() + } else { + alert('Could not notify') + } +} +``` + +If you try to use `// @ts-check` with the above code, you'll see a number of errors about the use of global variables: + +1. `Line 2` - `Property 'webkitNotifications' does not exist on type 'Window'.` +2. `Line 2` - `Cannot find name 'CAN_NOTIFY'.` +3. `Line 3` - `Property 'webkitNotifications' does not exist on type 'Window'.` + +If you want to continue using `// @ts-check` but are confident that these are not actual issues with your application, you have to let TypeScript know about these global variables. + +To start, [create a `jsconfig.json`](#javascript-project-jsconfigjson) at the root of your project: + +```json +{ + "compilerOptions": { }, + "exclude": [ + "node_modules", + "**/node_modules/*" + ] +} +``` + +Then reload VS Code to make sure the change is applied. The presence of a `jsconfig.json` lets TypeScript know that your Javascript files are part of a larger project. + +Now create a `globals.d.ts` file somewhere your workspace: + +```ts +interface Window { + webkitNotifications: any; +} + +declare var CAN_NOTIFY: number; +``` + +`d.ts` files are type declarations. In this case, `globals.d.ts` lets TypeScript know that a global `CAN_NOTIFY` exists and that a `webkitNotifications` property exists on `window`. You can read more about writing `d.ts` [here](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html). `d.ts` files do not change how JavaScript is evaluated, they are used only for providing better JavaScript language support. + +## Using tasks + +### Using the TypeScript compiler + +One of the key features of TypeScript is the ability to use the latest JavaScript language features, and emit code that can execute in JavaScript runtimes that don't yet understand those newer features. With JavaScript using the same language service, it too can now take advantage of this same feature. + +The TypeScript compiler `tsc` can down-level compile JavaScript files from ES6 to another language level. Configure the `jsconfig.json` with the desired options and then use the –p argument to make `tsc` use your `jsconfig.json` file, for example `tsc -p jsconfig.json` to down-level compile. + +Read more about the compiler options for down level compilation [here](/docs/languages/jsconfig.md#down-level-compilation-with-typescript-compiler). + +### Running Babel + +The [Babel](https://babeljs.io) transpiler turns ES6 files into readable ES5 JavaScript with Source Maps. You can easily integrate **Babel** into your workflow by adding the configuration below to your `tasks.json` file (located under the workspace's `.vscode` folder). The `group` setting makes this task the default **Task: Run Build Task** gesture. `isBackground` tells VS Code to keep running this task in the background. To learn more, go to [Tasks](/docs/editor/tasks.md). + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "watch", + "command": "${workspaceFolder}/node_modules/.bin/babel", + "args": ["src", "--out-dir", "lib", "-w", "--source-maps"], + "type": "shell", + "group": { "kind": "build", "isDefault": true }, + "isBackground": true + } + ] +} +``` + +Once you have added this, you can start **Babel** with the `kb(workbench.action.tasks.build)` (**Run Build Task**) command and it will compile all files from the `src` directory into the `lib` directory. + +> **Tip:** For help with Babel CLI see the instructions [here](https://babeljs.io/docs/setup/#installation). The example above uses the CLI option. + +## Disable JavaScript support + +If you prefer to use JavaScript language features supported by other JavaScript language tools such as [Flow](https://flow.org/), you can disable VS Code's built-in JavaScript support. You do this by disabling the built-in TypeScript language extension **TypeScript and JavaScript Language Features** (vscode.typescript-language-features) which also provides the JavaScript language support. + +To disable JavaScript/TypeScript support, go to the Extensions view (`kb(workbench.view.extensions)`) and filter on built-in extensions (**Show Built-in Extensions** in the **...** **More Actions** dropdown), then type 'typescript'. Select the **TypeScript and JavaScript Language Features** extension and press the **Disable** button. VS Code built-in extensions can not be uninstalled, only disabled, and can be re-enabled at any time. + +![TypeScript and JavaScript Language Features extension](images/working-with-javascript/disable-TS-language.png) diff --git a/docs/other/dotnet.md b/docs/other/dotnet.md new file mode 100644 index 0000000000000000000000000000000000000000..c1c7b56e73954154aeeac2b356581f39c3cb5e15 --- /dev/null +++ b/docs/other/dotnet.md @@ -0,0 +1,57 @@ +--- +Order: 2 +Area: other +TOCTitle: .NET Core +ContentId: AFFD7BDB-925E-4D02-828D-4E14360C70DA +PageTitle: .NET Core and Visual Studio Code +DateApproved: 3/6/2019 +MetaDescription: Get started writing and debugging .NET Core apps with Visual Studio Code. +MetaTags: +- .NET Core +- ASP.NET Core +- C# +--- +# Using .NET Core in Visual Studio Code + +[.NET Core](https://docs.microsoft.com/dotnet/articles/welcome) provides a fast and modular platform for creating server apps that run on Windows, Linux, and macOS. Use Visual Studio Code with the C# extension to get a powerful editing experience with [C# IntelliSense](https://docs.microsoft.com/visualstudio/ide/visual-csharp-intellisense) (smart code completion) and debugging. + +## Prerequisites + +Install the following: + +- [.NET Core](https://dotnet.microsoft.com/download). +- The [C# extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp) from the VS Code Marketplace. + +## Create a "Hello World" app + +1. Initialize a C# project: + + * Open a terminal and navigate to the folder in which you'd like to create the app. + * Enter the following command in the command shell: + + ```console + dotnet new console + ``` + +2. When the project folder is first opened in VS Code: + + * A "Would you like to add the required assets to build and debug your project?" notification appears at the top of the window. + * Select **Yes**. + +3. Run the app by entering the following command in the command shell: + + ```console + dotnet run + ``` + +Watch a video tutorial for further setup help on [Windows](https://channel9.msdn.com/Blogs/dotnet/Get-started-VSCode-Csharp-NET-Core-Windows), [macOS](https://channel9.msdn.com/Blogs/dotnet/Get-started-VSCode-NET-Core-Mac), or [Linux](https://channel9.msdn.com/Blogs/dotnet/Get-started-with-VS-Code-Csharp-dotnet-Core-Ubuntu). + +## Next steps + +* Continue exploring C# development: [Debug with VS Code and .NET Core](https://docs.microsoft.com/dotnet/articles/csharp/getting-started/with-visual-studio-code#debug) +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Working with C#](/docs/languages/csharp.md) - Learn about the great C# support you'll have when working on your .NET Core application. +* [Tasks](/docs/editor/tasks.md) - Running tasks with Gulp, Grunt, and Jake. Showing Errors and Warnings +* [.NET Core Docs](https://docs.microsoft.com/dotnet/core/) - Visit the .NET Core docs for more information on this powerful cross-platform development solution. +* [Deploying Applications to Azure](/docs/azure/deployment.md) - Deploy your app to [Azure](https://azure.microsoft.com). diff --git a/docs/other/images/ASPnet5/commands.png b/docs/other/images/ASPnet5/commands.png new file mode 100644 index 0000000000000000000000000000000000000000..35b421c761b92cd0d820636039806a1ddba1438c Binary files /dev/null and b/docs/other/images/ASPnet5/commands.png differ diff --git a/docs/other/images/ASPnet5/intellisense.png b/docs/other/images/ASPnet5/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..5dff31ae468848e4fef852fbd2d25535014f68a9 Binary files /dev/null and b/docs/other/images/ASPnet5/intellisense.png differ diff --git a/docs/other/images/office/appcatalog.png b/docs/other/images/office/appcatalog.png new file mode 100644 index 0000000000000000000000000000000000000000..ef258dc8c4a8cc2d6af8b8e47ae5a7aa55be3903 Binary files /dev/null and b/docs/other/images/office/appcatalog.png differ diff --git a/docs/other/images/office/exceladdin.png b/docs/other/images/office/exceladdin.png new file mode 100644 index 0000000000000000000000000000000000000000..6c832f5b809e2b763f12018dac582264a5169f85 Binary files /dev/null and b/docs/other/images/office/exceladdin.png differ diff --git a/docs/other/images/office/mailaddin.png b/docs/other/images/office/mailaddin.png new file mode 100644 index 0000000000000000000000000000000000000000..21dd2c0ec6528c0771d757dc00f4300da75ce2a1 Binary files /dev/null and b/docs/other/images/office/mailaddin.png differ diff --git a/docs/other/images/office/mailaddin01.png b/docs/other/images/office/mailaddin01.png new file mode 100644 index 0000000000000000000000000000000000000000..c590a8eddec408488aaf4e01fe7d4c7ade77bd99 Binary files /dev/null and b/docs/other/images/office/mailaddin01.png differ diff --git a/docs/other/images/office/mailaddin02.png b/docs/other/images/office/mailaddin02.png new file mode 100644 index 0000000000000000000000000000000000000000..4bed14ad1437dc858c49cf9cf726e9884f50c2e7 Binary files /dev/null and b/docs/other/images/office/mailaddin02.png differ diff --git a/docs/other/images/office/o365spadmin.png b/docs/other/images/office/o365spadmin.png new file mode 100644 index 0000000000000000000000000000000000000000..2d6f8912841b1da637002fb6f592dc819beebe4f Binary files /dev/null and b/docs/other/images/office/o365spadmin.png differ diff --git a/docs/other/images/office/officeaddinoverview.png b/docs/other/images/office/officeaddinoverview.png new file mode 100644 index 0000000000000000000000000000000000000000..b83215d7379850a5ba5137e099b00453b9b9965e Binary files /dev/null and b/docs/other/images/office/officeaddinoverview.png differ diff --git a/docs/other/images/office/owaaddaddin.png b/docs/other/images/office/owaaddaddin.png new file mode 100644 index 0000000000000000000000000000000000000000..03541f1da2847d92df4e3d713e21c56e499fe530 Binary files /dev/null and b/docs/other/images/office/owaaddaddin.png differ diff --git a/docs/other/images/office/owamanageaddins.png b/docs/other/images/office/owamanageaddins.png new file mode 100644 index 0000000000000000000000000000000000000000..fad0ce967202d5c4c32d32102a2b90f60d682537 Binary files /dev/null and b/docs/other/images/office/owamanageaddins.png differ diff --git a/docs/other/images/office/runlocally.png b/docs/other/images/office/runlocally.png new file mode 100644 index 0000000000000000000000000000000000000000..713400ba43ed28d375feb3961c51c1629bcc33e6 Binary files /dev/null and b/docs/other/images/office/runlocally.png differ diff --git a/docs/other/images/office/yoofficemanifest.png b/docs/other/images/office/yoofficemanifest.png new file mode 100644 index 0000000000000000000000000000000000000000..3788fea54f5af66901529e22e125f7fd430f04a7 --- /dev/null +++ b/docs/other/images/office/yoofficemanifest.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3012ff83ff2408ed143f3b4b7cef9b651a62f52e26194c10093af2c1f7bab63d +size 414496 diff --git a/docs/other/images/unity/Unity_Preferences_External_Script_Editor.gif b/docs/other/images/unity/Unity_Preferences_External_Script_Editor.gif new file mode 100644 index 0000000000000000000000000000000000000000..bee9f967ab058cf614d92b18b49f043548ced8a2 Binary files /dev/null and b/docs/other/images/unity/Unity_Preferences_External_Script_Editor.gif differ diff --git a/docs/other/images/unity/filteredfiles.png b/docs/other/images/unity/filteredfiles.png new file mode 100644 index 0000000000000000000000000000000000000000..578d8e28724062e388646ce23cf661a3d0f2c5f0 Binary files /dev/null and b/docs/other/images/unity/filteredfiles.png differ diff --git a/docs/other/images/unity/omnisharp.png b/docs/other/images/unity/omnisharp.png new file mode 100644 index 0000000000000000000000000000000000000000..763848ad18f9c4e2a106f333f78d23ff0711149d Binary files /dev/null and b/docs/other/images/unity/omnisharp.png differ diff --git a/docs/other/images/unity/peekreferences.png b/docs/other/images/unity/peekreferences.png new file mode 100644 index 0000000000000000000000000000000000000000..093d3fdb719391f9d7d45f53ee761334d1cc87a6 Binary files /dev/null and b/docs/other/images/unity/peekreferences.png differ diff --git a/docs/other/images/unity/selectsln.png b/docs/other/images/unity/selectsln.png new file mode 100644 index 0000000000000000000000000000000000000000..bcfe5870758fa9d3f4c49b6e1547aac02590b66e Binary files /dev/null and b/docs/other/images/unity/selectsln.png differ diff --git a/docs/other/images/unity/unfilteredfiles.png b/docs/other/images/unity/unfilteredfiles.png new file mode 100644 index 0000000000000000000000000000000000000000..73bc2712a8f34a6f228d888c12be9553f98b413b Binary files /dev/null and b/docs/other/images/unity/unfilteredfiles.png differ diff --git a/docs/other/images/unity/wow.gif b/docs/other/images/unity/wow.gif new file mode 100644 index 0000000000000000000000000000000000000000..2be9512b3416b3834ceb73574f76aea89f9931b7 --- /dev/null +++ b/docs/other/images/unity/wow.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:84978fdf82642419c7dde5a22e13c099a2e17c3bba8c778d804ba8b5d21a857d +size 579610 diff --git a/docs/other/office.md b/docs/other/office.md new file mode 100644 index 0000000000000000000000000000000000000000..e98c43618d95aa83b9a051bd862bc5b74ac019ec --- /dev/null +++ b/docs/other/office.md @@ -0,0 +1,119 @@ +--- +Order: 4 +Area: other +TOCTitle: Office +ContentId: 8661D491-297F-4778-B10B-588005CCD443 +PageTitle: Office Add-ins with Visual Studio Code +DateApproved: 3/5/2018 +MetaDescription: See how to use the features of Visual Studio Code and integrate your Add-in with Office/Office 365. +--- +# Office Add-ins with Visual Studio Code + +[Office Add-ins](https://dev.office.com/getting-started/addins) run inside an Office application and can interact with the contents of the Office document using the rich JavaScript API. + +![Office Add-in overview](images/office/officeaddinoverview.png) + +Under the hood, an Office Add-in is just a web app that you can host anywhere. Using a `manifest.xml` file, you tell the Office application where your web app is located and how you want it to appear. The Office application takes care of hosting it within Office. + +## Step 1: Get set up + +Follow the instructions to [Create an Office Add-in using any editor](https://dev.office.com/blogs/creating-office-add-ins-with-any-editor-introducing-yo-office) to install the necessary prerequisites, and use Yo Office to create a new add-in project. The following table lists the project attributes to select in the Yeoman generator. + +| Option | Value | +|:------|:------| +|New subfolder | (accept the default) | +| Add-in name | Outlook Add-in | +| Supported Office application | (select Outlook) | +| Create new add-in | Yes, I want a new add-in | +| Add [TypeScript](https://www.typescriptlang.org/) | No | +| Choose framework | Jquery | + +## Use Visual Studio Code to develop your Office Add-in! + +Visual Studio Code is a great tool to help you develop your custom Office Add-ins regardless if they are for Outlook, Word, Excel, PowerPoint and run in the web clients, Windows clients, iOS clients or on macOS! + +### Getting started + +Open the project in Visual Studio Code by entering the following on the command line from within the same folder where you ran the generator: + +```bash +code . +``` + +![My-office-add-in-manifest.xml in VS Code](images/office/yoofficemanifest.png) + +Open the `manifest.xml` file that was created by Yo Office and locate the `SourceLocation` node. Update this URL to the URL where you will host the Add-in. + +>**Tip:** If you are using an Azure Web App as the host, the URL will look something like `https://[name-of-your-web-app].azurewebsites.net/[path-to-add-in]`. If you are using the self-hosted option listed above, it will be `http://localhost:3000/[path-to-add-in]`. + +### Debugging your Office Add-in + +VS Code does not currently support client-side debugging. To debug your client-side Add-in, you can use the Office web clients and open the browser's developer tools and debug the Add-in just like any other client-side JavaScript application. + +If you are using Node.js or ASP.NET Core for server-side logic that supports your Office Add-in, refer to the [Debugging](/docs/editor/debugging.md) page to configure VS Code for debugging either of these runtimes. + +## Install the Add-in + +Office Add-ins must be installed, or registered, with the Office application in order to load. This is done using the `manifest.xml` file you modified earlier. + +### Side loading Mail Add-ins + +Mail Add-ins can be installed within the Outlook Web App. Browse to your [Outlook Web App](https://mail.office365.com) and login. Once logged in, click the gear icon in the top-right section and select **Manage add-ins**: + +![Manage Add-ins](images/office/owamanageaddins.png) + +On the **Manage add-ins** page, select the *+* icon and then select **Add from a file**. + +![Add from File](images/office/owaaddaddin.png) + +Locate the `manifest.xml` file for your custom Add-in and install it, accepting all prompts when installing it. + +Once that's done, select an existing email and you will see a horizontal bar below the email header that includes the Add-in: + +![The Add-in in action in mail](images/office/mailaddin.png) + +Next try creating an email, click the **Add-ins** or **Apps** menu item to get the Task Pane to appear: + +![Open task pane](images/office/mailaddin01.png) + +Select the Add-in and see it appear in the Task Pane: + +![Add-in in task pane](images/office/mailaddin02.png) + +### Deploying Add-ins to the Office 365 Tenancy's App Catalog + +All Office Add-ins (including Mail Add-ins) can be installed from your Office 365 tenancy's App Catalog site. Log in to your [Office 365 Portal](http://portal.office365.com). In the left-hand navigation, towards the bottom, select the **Admin / SharePoint** option: + +![Office SharePoint Admin](images/office/o365spadmin.png) + +From the **SharePoint Admin Center**, select the **Apps** option in the left-hand menu and then select the **App Catalog**. On the **App Catalog** page, select the **Apps for Office** option and upload the `manifest.xml` file. + +![App Catalogue](images/office/appcatalog.png) + +### Install Content & Task Pane Add-ins in Word / Excel / PowerPoint + +Depending on the type of Add-in you created, you can add it to one of the Office applications. Task Pane and Content Add-ins can be installed in Word, Excel & PowerPoint. Mail Add-ins can be installed in Outlook. + +To install an Add-in within an Office application, select the **Insert** tab and click the **Office Add-ins** button, as shown here using the Excel Web App: + +![Excel Add-in](images/office/exceladdin.png) + +Using the Office Add-ins dialog you can select Add-ins you've uploaded to your Office 365 tenancy's App Catalog (*listed under My Organization*) or acquire Add-ins from the Office Store. + +## Next steps + +Check out the other pages on the VS Code site to find out how you can leverage more capabilities of the editor when creating custom Office Add-ins: + +- [Language Overview](/docs/languages/overview.md) - You can write Office Add-ins in many languages. Find out what VS Code has to offer. +- [User Interface](/docs/getstarted/userinterface.md) - Just starting out with VS Code? This is worth reviewing. +- [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. + +## Common questions + +### Can I create an Office Add-in with the generator and use VS Code regardless of the language or client-side framework? + +Yes, you can. You can use pure HTML, Angular, Ember, React, Aurelia... anything you like! + +### Can I use TypeScript to create my Office Add-in? + +Absolutely, VS Code has great support for [TypeScript](/docs/languages/typescript.md)! diff --git a/docs/other/unity.md b/docs/other/unity.md new file mode 100644 index 0000000000000000000000000000000000000000..6a9f6780e749b0f2b30edc3ab5ba2775a67ea01e --- /dev/null +++ b/docs/other/unity.md @@ -0,0 +1,141 @@ +--- +Order: 3 +Area: other +TOCTitle: Unity +ContentId: 75CD2FA6-2F91-428A-A88D-880611AE75A0 +PageTitle: Visual Studio Code and Unity +DateApproved: 5/2/2017 +MetaDescription: Visual Studio Code can replace MonoDevelop as the editor for Unity +--- +# Unity Development with VS Code + +Visual Studio Code can be a great companion to Unity for editing and debugging C# files. All of the [C#](/docs/languages/csharp.md) features are supported and more. In the screen below, you can see code colorization, bracket matching, IntelliSense, CodeLens and that's just the start. + +![Unity Example](images/unity/wow.gif) + +Read on to find out how to configure Unity and your project to get the best possible experience. + +## Prerequisites + +From [Using .NET Core in Visual Studio Code](/docs/other/dotnet.md): + +1. Install [.NET SDK](/docs/other/dotnet.md) (.NET Core), which includes the `dotnet` command. + +1. [Windows only] Logout or restart Windows to allow changes to `%PATH%` to take effect. + +1. [macOS only] To avoid seeing "Some projects have trouble loading. Please review the output for more details", make sure to install the latest stable [Mono](http://www.mono-project.com/download/) release. + + **Note**: This version of Mono, which is installed into your system, will not interfere with the version of MonoDevelop that is installed by Unity. + +1. Install the [C# extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp) from the VS Code Marketplace. + +## Setup VS Code as Unity Script Editor + +Open up **Unity Preferences**, **External Tools**, then browse for the Visual Studio Code executable as **External Script Editor**. + +![Unity Preferences](images/unity/Unity_Preferences_External_Script_Editor.gif) + +> The Visual Studio Code executable can be found at `/Applications/Visual Studio Code.app` on macOS, `C:\users\{username}\AppData\Local\Programs\Microsoft VS Code\Code.exe` on Windows by default. + +**Unity has built-in support for opening scripts in Visual Studio Code** as an external script editor on Windows and macOS. Unity will detect when Visual Studio Code is selected as an external script editor and pass the correct arguments to it when opening scripts from Unity. Unity will also set up a default `.vscode/settings.json` with file excludes, if it does not already exist (from [Unity 5.5 Release notes](https://unity3d.com/unity/whats-new/unity-5.5.0)). + +## Editing Evolved + +With the solution file selected, you are now ready to start editing with VS Code. Here is a list of some of the things you can expect: + +* Syntax Highlighting +* Bracket matching +* IntelliSense +* Snippets +* CodeLens +* Peek +* Go-to Definition +* Code Actions/Lightbulbs +* Go to symbol +* Hover + +Two topics that will help you are [Basic Editing](/docs/editor/codebasics.md) and [C#](/docs/languages/csharp.md). In the image below, you can see VS Code showing hover context, peeking references and more. + +![editing evolved example](images/unity/peekreferences.png) + +## Unity Extensions + +The community is continually developing more and more valuable extensions for Unity. Here are some popular extensions that you might find useful. You can search for more extensions in the [VS Code Extension Marketplace](https://marketplace.visualstudio.com/search?term=Unity&target=VSCode). + +
+ +The extensions shown above are dynamically queried. Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com/vscode). + +## Enabling code completion (For recent versions of Unity) + +If you are installing VS Code for the first time, you might be missing targeting packs required for Unity's code-completion (IntelliSense) in VS Code. + +Targeting pack download links: + +* [Windows: .NET Framework 4.6 Targeting Pack](https://www.microsoft.com/en-us/download/details.aspx?id=48136) +* [macOS: Download .NET SDK](https://dotnet.microsoft.com/learn/dotnet/hello-world-tutorial#macos) + +Steps: + +1. Stop VS Code or Unity running. +2. Download and install the targeting pack for your targeted framework version / preferred version from one of the above links. +3. Start Unity. +4. Create and/or open an existing script in VS Code, through Unity, and you should now see code completions. + +## Next steps + +Read on to learn more about: + +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Debugging](/docs/editor/debugging.md) - how to use the debugger with your project +* [C#](/docs/languages/csharp.md) - learn about the C# support in VS Code + +## Common questions + +### I don't have IntelliSense + +You need to ensure that your solution is open in VS Code (not just a single file). Open the folder with your solution and you usually will not need to do anything else. If for some reason VS Code has not selected the right solution context, you can change the selected project by clicking on the OmniSharp flame icon on the status bar. + +![OmniSharp Flame on the Status Bar](images/unity/omnisharp.png) + +Choose the `-CSharp` version of the solution file and VS Code will light up. + +![Choose Solution](images/unity/selectsln.png) + +### How can I change the file exclusions? + +Unity creates a number of additional files that can clutter your workspace in VS Code. You can easily hide these so that you can focus on the files you actually want to edit. + +To do this, add the following JSON to your [workspace settings](/docs/getstarted/settings.md). + +```json + // Configure glob patterns for excluding files and folders. + "files.exclude": { + "**/.git": true, + "**/.DS_Store": true, + "**/*.meta": true, + "**/*.*.meta": true, + "**/*.unity": true, + "**/*.unityproj": true, + "**/*.mat": true, + "**/*.fbx": true, + "**/*.FBX": true, + "**/*.tga": true, + "**/*.cubemap": true, + "**/*.prefab": true, + "**/Library": true, + "**/ProjectSettings": true, + "**/Temp": true + } +``` + +As you can see below this will clean things up a lot... + +Before|After +------|----- +![Unfiltered files](images/unity/unfilteredfiles.png)|![filtered files](images/unity/filteredfiles.png) + +### How can I debug Unity? + +Install the [Debugger for Unity](https://marketplace.visualstudio.com/items/Unity.unity-debug) extension. And check out [Debugging with VS Code](/docs/editor/debugging.md) to learn more about VS Code debugging support. diff --git a/docs/python/debugging.md b/docs/python/debugging.md new file mode 100644 index 0000000000000000000000000000000000000000..71891024e9c8a19878412b8a5789f13b27d0fd6d --- /dev/null +++ b/docs/python/debugging.md @@ -0,0 +1,494 @@ +--- +Order: 4 +Area: python +TOCTitle: Debugging +ContentId: 3d9e6bcf-eae8-4c94-b857-89225b5c4ab5 +PageTitle: Debugging configurations for Python apps in Visual Studio Code +DateApproved: 01/17/2019 +MetaDescription: Details on configuring the Visual Studio Code debugger for different Python applications. +MetaSocialImage: images/tutorial/social.png +--- +# Python debug configurations in Visual Studio Code + +The Python extension supports debugging of a number of types of Python applications. For a short walkthrough of basic debugging, see [Tutorial - Configure and run the debugger](/docs/python/python-tutorial.md#configure-and-run-the-debugger). Also see the [Flask tutorial](/docs/python/tutorial-flask.md). Both tutorials demonstrate core skills like setting breakpoints and stepping through code. + +**For general debugging features** such as inspecting variables, setting breakpoints, and other activities that aren't language-dependent, review [VS Code debugging](/docs/editor/debugging.md). + +This article addresses only those considerations that are specific to Python, mainly Python-specific debugging *configurations*, including the necessary steps for specific app types and remote debugging. + +## Initialize configurations + +A configuration drives VS Code's behavior during a debugging session. Configurations are defined in a `launch.json` file that's stored in a `.vscode` folder in your workspace. + +To initialize debug configurations, first select the Debug View in the sidebar: + +![Debug icon](images/debugging/debug-icon.png) + +If you don't yet have any configurations defined, you'll see "No Configurations" in the drop-down list, and a dot on the settings icon: + +![Debug toolbar settings command](images/debugging/debug-settings-warning-icon.png) + +To generate a `launch.json` file with Python configurations, do the following steps: + +1. Select the settings button (circled in the image above) or use the **Debug** > **Open configurations** menu command. + +1. In the **Select Environment** drop-down list that appears, select **Python**. + +1. The Python extension then creates and opens a `launch.json` file that contains number of pre-defined configurations. You can modify configurations (to add arguments, for example), and also add custom configurations. + +The details of configuration properties are covered later in this article under [Standard configuration and options](#set-configuration-options). Additional configurations are also described in this article under [Debugging specific app types](#debugging-specific-app-types). + +## Choose a configuration + +To select a debugging configuration, select the Debug View in the sidebar, then select an option of your choice from the drop-down list: + +![Selecting a debug configuration](images/debugging/debug-configurations.png) + +> **Note**: Previous versions of the Python extension used slightly different names for the configurations as shown in the above graphic, but they generally work the same. + +By default, VS Code shows only the most common configurations provided by the Python extension. You can select other configurations to include in `launch.json` by using the **Add Configuration** command shown in the list and in the `launch.json` editor. When you use the command, VS Code prompts you with a list of all available configurations (be sure to scroll down to see all the Python options): + +![Adding a new Python debugging configuration](images/debugging/add-configuration.png) + +See [Debugging specific app types](#debugging-specific-app-types) for details on all of these configurations. + +During debugging, the Status Bar shows the current configuration on the lower left; to its right is the current debugging interpreter. Selecting the configuration brings up a list from which you can choose a different configuration: + +![Debugging Status Bar](images/debugging/debug-status-bar.png) + +By default, the debugger uses the same `python.pythonPath` workspace setting as for other features of VS Code. To use a different interpreter for debugging specifically, set the value for `pythonPath` in `launch.json` for the applicable debugger configuration as described in the next section. Alternately, select the named interpreter on the Status Bar to select a different one, which updates `python.pythonPath`. + +## Set configuration options + +When you first create `launch.json`, there are two standard configurations that run the active file in the editor in either the integrated terminal (inside VS Code) or the external terminal (outside of VS Code): + +```json +{ + "name": "Python: Current File (Integrated Terminal)", + "type": "python", + "request": "launch", + "program": "${file}", + "console": "integratedTerminal" +}, +{ + "name": "Python: Current File (External Terminal)", + "type": "python", + "request": "launch", + "program": "${file}", + "console": "externalTerminal" +} +``` + +The specific settings are described in the following sections. You can also add other settings, such as `args`, that aren't included in the standard configurations. + +> **Tip**: It's often helpful in a project to create a configuration that runs a specific startup file. For example, if you want to always launch `startup.py` with the arguments `--port 1593` when you start the debugger, create a configuration entry as follows: +> +> ```json +> { +> "name": "Python: startup.py", +> "type": "python", +> "request": "launch", +> "program": "${workspaceFolder}/startup.py", +> "args" : ["--port", "1593"] +> }, +> ``` + +### `name` + +Provides the name for the debug configuration that appears in the VS Code drop-down list. + +### `type` + +Identifies the type of debugger to use; leave this set to `python` for Python code. + +### `request` + +Specifies the mode in which to start debugging: + +- `launch`: start the debugger on the file specified in `program` +- `attach`: attach the debugger to an already running process. See [Remote debugging](#remote-debugging) for an example. + +### `program` + +Provides the fully qualified path to the python program's entry module (startup file). The value `${file}`, often used in default configurations, uses the currently active file in the editor. By specifying a specific startup file, you can always be sure of launching your program with the same entry point regardless of which files are open. For example: + +```json +"program": "/Users/Me/Projects/PokemonGo-Bot/pokemongo_bot/event_handlers/__init__.py", +``` + +You can also rely on a relative path from the workspace root. For example, if the root is `/Users/Me/Projects/PokemonGo-Bot` then you can use the following: + +```json +"program": "${workspaceFolder}/pokemongo_bot/event_handlers/__init__.py", +``` + +### `pythonPath` + +Points to the Python interpreter to be used for debugging, which can be a folder containing a Python interpreter. The value can use variables like `${workspaceFolder}` and `${workspaceFolder}/.venv`. + +If not specified, this setting defaults to the interpreter identified in the `python.pythonPath` setting, which is equivalent to using the value `${config:python.pythonPath}`. To use a different interpreter, specify its path instead in the `pythonPath` property of a debug configuration. + +You can specify platform-specific paths by placing `pythonPath` within a parent object named `osx`, `windows`, or `linux`. For example, the configuration for PySpark uses the following values: + +```json +"osx": { + "pythonPath": "^\"\\${env:SPARK_HOME}/bin/spark-submit\"" +}, +"windows": { + "pythonPath": "^\"\\${env:SPARK_HOME}/bin/spark-submit.cmd\"" +}, +"linux": { + "pythonPath": "^\"\\${env:SPARK_HOME}/bin/spark-submit\"" +}, +``` + +Alternately, you can use a custom environment variable that's defined on each platform to contain the full path to the Python interpreter to use, so that no additional folder paths are needed. + +### `args` + +Specifies arguments to pass to the Python program. Each element of the argument string that's separated by a space should be contained within quotes, for example: + +```json +"args": ["--quiet", "--norepeat", "--port", "1593"], +``` + +### `stopOnEntry` + +When set to `True`, breaks the debugger at the first line of the program being debugged. If omitted (the default) or set to `False`, the debugger runs the program to the first breakpoint. + +### `console` + +Specifies how program output is displayed. + +| Value | Where output is displayed | +|--- | --- | +| `"none"` | VS Code debug console | +| `"integratedTerminal"` (default) | [VS Code Integrated Terminal](/docs/editor/integrated-terminal.md) | +| `"externalTerminal"` | Separate console window | + +### `cwd` + +Specifies the current working directory for the debugger, which is the base folder for any relative paths used in code. If omitted, defaults to `${workspaceFolder}` (the folder open in VS Code). + +As an example, say `${workspaceFolder}` contains a `py_code` folder containing `app.py`, and a `data` folder containing `salaries.csv`. If you start the debugger on `py_code/app.py`, then the relative paths to the data file vary depending on the value of `cwd`: + +| cwd | Relative path to data file | +| --- | --- | +| Omitted or `${workspaceFolder}` | `data/salaries.csv` | +| `${workspaceFolder}/py_code` | `../data/salaries.csv` | +| `${workspaceFolder}/data` | `salaries.csv` | + +### `debugOptions` + +An array of additional options: + +| Option | Description | +| --- | --- | +| `"RedirectOutput"` (default) | Causes the debugger to print all output from the program into the VS Code debug output window. If this setting is omitted, all program output is not displayed in the debugger output window. This option is typically omitted when using `"console": "integratedTerminal"` or `"console": "externalTerminal"` because there's no need to duplicate the output in the debug console. | +| `"DebugStdLib"` | Enabled debugging of standard library functions. | +| `"Django"` | Activates debugging features specific to the Django web framework. | +| `"Sudo"` | When used with `"console": "externalTerminal"`, allows for debugging apps that require elevation. Using an external console is necessary to capture the password. | +| `"Pyramid"` | When set to true, ensures that a Pyramid app is launched with [the necessary `pserve` command](https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/startup.html?highlight=pserve). | + +### `env` + +Sets optional environment variables for the debugger process beyond system environment variables, which the debugger always inherits. + +### `envFile` + +Optional path to a file that contains environment variable definitions. See [Configuring Python environments - environment variable definitions file](/docs/python/environments.md#environment-variable-definitions-file). + +### `gevent` + +If set to `true`, enables debugging of [gevent monkey-patched code](http://www.gevent.org/intro.html). + +## Invoking a breakpoint in code + +In your Python code, you can call `breakpoint()` at any point where you want to pause the debugger during a debugging session. + +## Breakpoint validation + +The Python extension automatically detects breakpoints that are set on non-executable lines, such as `pass` statements or the middle of a multiline statement. In such cases, running the debugger moves the breakpoint to nearest valid line to ensure that code execution stops at that point. + +## Attach to a local script + +In some scenarios, you need to debug a Python script that's invoked locally by another process. For example, you may be debugging a web server that runs different Python scripts for specific processing jobs. In such cases, you need to attach the VS Code debugger to the script once it's been launched: + +1. Run VS Code, open the folder or workspace containing the script, and create a `launch.json` for that workspace if one doesn't exist already. + +1. In the script code, add the following and save the file: + + ```python + import ptvsd + + # 5678 is the default attach port in the VS Code debug configurations + print("Waiting for debugger attach") + ptvsd.enable_attach(address=('localhost', 5678), redirect_output=True) + ptvsd.wait_for_attach() + breakpoint() + ``` + +1. Open a terminal using **Terminal: Create New Integrated Terminal**, which activates the script's selected environment. + +1. In the terminal, install the ptvsd package with `python -m pip install --upgrade ptvsd`. + +1. In the terminal, start Python with the script, for example, `python3 myscript.py`. You should see the "Waiting for debugger attach" message that's included in the code, and the script halts at the `ptvsd.wait_for_attach()` call. + +1. Switch to the Debug view, select **Python: Attach** from the debugger drop-down list, and start the debugger. + +1. The debugger should stop on the `breakpoint()` call, from which point you can use the debugger normally. You can, of course, set other breakpoints in the script code instead of using `breakpoint()`. + +> **Note**: In the future, the Python extension will support attaching the debugger by process ID instead of host and port. See [Issue 1078](https://github.com/Microsoft/vscode-python/issues/1078). + +## Remote debugging + +Remote debugging allows you to step through a program locally within VS Code while it runs on a remote computer. It is not necessary to install VS Code on the remote computer. + +1. Both computers: make sure that identical source code is available. + +1. Both computers: install [ptvsd](https://pypi.org/project/ptvsd/) using `python -m pip install --upgrade ptvsd` into your environment (while using a form of virtual environment is not required, it is a recommended best practice). + +1. Remote computer: open the port you wish to use for debugging in the appropriate firewall or other networking configuration. + +1. Remote computer: there are two ways to specify how to attach to the remote process. You may need to specify the remote computer's private IP address, if applicable (Linux VMs on Azure, for example, have both a public and private address). If you use the public IP address, you might see the error "Cannot assign requested address." + + 1. In the source code, add the following lines, replacing `address` with the remote computer's IP address and port number (IP address 1.2.3.4 is shown here for illustration only). + + ```python + import ptvsd + + # Allow other computers to attach to ptvsd at this IP address and port. + ptvsd.enable_attach(address=('1.2.3.4', 3000), redirect_output=True) + + # Pause the program until a remote debugger is attached + ptvsd.wait_for_attach() + ``` + + The IP address used in `enable_attach` should be the remote computer's private IP address. You can then launch the program normally, causing it to pause until the debugger attaches. + + 1. Launch the remote process through ptvsd, for example: + + ```bash + python3 -m ptvsd --host 1.2.3.4 --port 3000 --wait -m myproject + ``` + + This starts the package `myproject` using `python3`, with the remote computer's private IP address of `1.2.3.4` and listening on port `3000` (you can also start the remote Python process by specifying a file path instead of using `-m`). + +1. Local computer: **Only if you modified the source code on the remote computer as outlined above**, then in the source code, add a commented-out copy of the same code added on the remote computer. Adding these lines makes sure that the source code on both computers matches line by line. + + ```python + #import ptvsd + + # Allow other computers to attach to ptvsd at this IP address and port. + #ptvsd.enable_attach(address=('1.2.3.4', 3000), redirect_output=True) + + # Pause the program until a remote debugger is attached + #ptvsd.wait_for_attach() + ``` + +1. Local computer: switch to Debug View in VS Code, select the **Python: Attach** configuration, and select the settings (gear) icon to open `launch.json` to that configuration. + +1. Local computer: Modify the configuration so that `remoteRoot` provides the location of the program on the remote computer's file system. Also modify `host` and `port` to match the values in the `ptvsd.enable_attach` call added to the source code, except that you need to use the remote computer's public IP address for `host`. You might also change `name` to specifically identify the configuration. For example: + + ```js + { + "name": "Python Attach (Remote Debug 192.168.34.156)", + "type": "python", + "request": "attach", + "pathMappings": [ + { + "localRoot": "${workspaceFolder}", // You may also manually specify the directory containing your source code. + "remoteRoot": "~/hello" // Linux example; adjust as necessary for your OS and situation. + } + ], + "port": 3000, // Set to the remote port. + "host": "1.2.3.4" // Set to your remote host's public IP address. + } + ``` + +1. Local computer: set a breakpoint in the code where you want to start debugging. + + > **Tip**: setting a single breakpoint on the statement immediately following the `ptvsd.wait_for_attach()` line may not work. Set at least one other breakpoint on another statement. + +1. Local computer: start the VS Code debugger using the modified **Python Attach** configuration. VS Code should stop on your locally set breakpoints, allowing you to step through the code, examine variables, and perform all other debugging actions. Expressions that you enter in the **Debug Console** are run on the remote computer as well. + + Text output to stdout, as from `print` statements, appears on both computers. Other outputs, such as graphical plots from a package like matplotlib, however, appear only on the remote computer. + +1. During remote debugging, the debugging toolbar appears as below: + + ![Debugging toolbar during remote debugging](images/debugging/remote-debug-toolbar.png) + + On this toolbar, the disconnect button (`kb(workbench.action.debug.stop)`) stops the debugger and allows the remote program to run to completion. The restart button (`kb(workbench.action.debug.restart)`) restarts the debugger on the local computer but does **not** restart the remote program. Use the restart button only when you've already restarted the remote program and need to reattach the debugger. + +### Debugging over SSH + +In some cases, you may want or need to use a secure connection to the remote computer when debugging. On Windows computers, you may need to install [OpenSSH](http://sshwindows.sourceforge.net/) to have the `ssh` command. + +On the remote computer: + +1. Enable port forwarding by opening the `sshd_config` config file (found under `/etc/ssh/` on Linux and under `%programfiles(x86)%/openssh/etc` on Windows) and adding or modifying the following setting: + + ``` + AllowTcpForwarding yes + ``` + +1. Restart the SSH server. On Linux/macOS, run `sudo service ssh restart`; on Windows, run `services.msc`, locate and select OpenSSH in the list of services, and select **Restart**. + +1. Start the Python program and let it wait for the debugger to attach as described in the previous section. + +On the local computer: + +1. Create an SSH tunnel by running `ssh -L sourceport:localhost:destinationport user@remoteaddress`, using a selected port for `destinationport` and the appropriate username and the remote computer's IP address in `user@remoteaddress`. For example, to use port 3000 on IP address 1.2.3.4, the command would be `ssh -L 3000:localhost:3000 user@1.2.3.4`. + +1. Verify that you can see a prompt in the SSH session. + +1. In VS Code, set the port in the debug configuration of `launch.json` to match the port used in the `ssh` command and set the host to `localhost`. You use `localhost` here because you've set up the SSH tunnel. + +1. Launch the program and attach the debugger as described in the previous section. + +## Debugging specific app types + +The configuration drop-down provides a variety of different options for general app types: + +| Configuration | Description | +| --- | --- | +| Attach | See [Remote debugging](#remote-debugging) in the previous section. | +| Django | Specifies `"program": "${workspaceFolder}/manage.py"`, `"args": ["runserver", "--noreload", "--nothreading"]`, and `"console": "integratedTerminal"`. Also adds `"django": true` to enable debugging of Django HTML templates. Note that automatic reloading of Django apps is not possible while debugging. | +| Flask | See [Flask debugging](#flask-debugging) below. | +| Gevent | Adds `"gevent": true` to the standard integrated terminal configuration. | +| Pyramid | Removes `program`, adds `"args": ["${workspaceFolder}/development.ini"]`, adds `"jinja": true` for enabling template debugging, and adds `"pyramid": true` to ensure that the program is launched with [the necessary `pserve` command](https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/startup.html?highlight=pserve). | +| PySpark | Runs the program using PySpark instead of the default interpreter, using platform-specific values for `pythonPath` as shown earlier under the [pythonPath option](#pythonpath). | +| Scrapy | Specifies `"module": "scrapy"` and adds `"args": ["crawl", "specs", "-o", "bikes.json"]`. | +| Watson | Specifies `"program": "${workspaceFolder}/console.py"` and `"args": ["dev", "runserver", "--noreload=True"]`. | + +Specific steps are also needed for remote debugging and Google App Engine. For details on debugging unit tests (including nosetest), see [Unit testing](/docs/python/unit-testing.md). + +To debug an app that requires administrator privileges, use `"console": "externalTerminal"` and include "Sudo" in `debugOptions`. + +### Flask debugging + +```json +{ + "name": "Python: Flask", + "type": "python", + "request": "launch", + "module": "flask", + "env": { + "FLASK_APP": "app.py" + }, + "args": [ + "run", + "--no-debugger", + "--no-reload" + ], + "jinja": true +}, +``` + +As you can see, this configuration specifies `"env": {"FLASK_APP": "app.py"}` and `"args": ["run", "--no-debugger","--no-reload"]`. The `"module": "flask"` property is used instead of `program`. (You may see `"FLASK_APP": "${workspaceFolder}/app.py"` in the `env` property, in which case modify the configuration to refer to only the filename. Otherwise you may see "Cannot import module C" errors where C is a drive letter.) + +The `"jinja": true` setting also enables debugging for Flask's default Jinja templating engine. + +If you want to run Flask's development server in development mode, use the following configuration: + +```json +{ + "name": "Python: Flask (development mode)", + "type": "python", + "request": "launch", + "module": "flask", + "env": { + "FLASK_APP": "app.py", + "FLASK_ENV": "development" + }, + "args": [ + "run" + ], + "jinja": true +}, +``` + +### Google App Engine debugging + +Google App Engine launches an app by itself, so launching it in the VS Code debugger isn't directly possible. What's required instead is to use ptvsd in the app and then launch Google App Engine in a mode that allows VS Code to attach its debugger. + +![Debugging Google App Engine](images/debugging/debugGAE.gif) + +1. [Download ptvsd](https://pypi.python.org/pypi/ptvsd) and extract its files into a ptvsd folder in your working folder. (If using a different folder, modify the path in the `pydev_startup.py` file created in step 4). + +1. Create a `tasks.json` file with the following contents: + + ```json + { + "version": "2.0.0", + "tasks": [ + { + "label": "Launch Google App Engine", + "command": "python", + "type": "shell", + "args": [ + "/usr/local/google_appengine/dev_appserver.py", + "--python_startup_script=${workspaceFolder}/pydev_startup.py", + "--automatic_restart=no", + "--max_module_instances=default:1", + "${workspaceFolder}/app.yaml" + ] + } + ] + } + ``` + +1. On Windows and Linux, replace the first item in `args` with the path to wherever Google App Engine is installed (the path shown in the source code above is for macOS). + +1. Create a file named `pydev_startup.py` in your project root with the following contents, modified as noted: + ```python + import sys + import os + + # Assuming that pdvsd is located in the working folder + sys.path.append(os.getcwd()) + + import ptvsd + # Modify the port number as desired; you're debugging locally so the values don't matter. + # However, be sure the port is not blocked on your computer. + ptvsd.enable_attach(address=('0.0.0.0', 3000), redirect_output=True) + + # The debug server has started and you can now use VS Code to attach to the application for debugging + print("Google App Engine has started; ready to attach the debugger") + ``` +1. Create a `launch.json` configuration using the **Attach (Remote Debug)** configuration as a template. Make sure the port value matches what's in the source code above. +1. Add `"preLaunchTask": "python"` to `launch.json`. +1. From the Command Palette, run the **Run Build Task** command. This command opens the Tasks output window where you see various messages. +1. Once you see the message "Google App Engine has started; ready to attach the debugger," start the VS Code debugger using the remote debugging configuration. +1. Set breakpoints where you want, then start the browser to start the app. + + + +## Troubleshooting + +There are many reasons why the debugger may not work. Oftentimes the debug console reveals specific causes, but two specific reasons are as follows: + +- The path to the python executable is incorrect: check the value of `pythonPath` in your user settings. +- There are invalid expressions in the watch window (as in the example below): clear all expressions from the Watch window and restart the debugger. + + ```python + Traceback (most recent call last): + File ".../visualstudio_py_debugger.py", line 1646, in loop + cmd() + File ".../visualstudio_py_debugger.py", line 1918, in command_execute_code + thread.run_on_thread(text, cur_frame, eid, frame_kind, repr_kind) + File ".../visualstudio_py_debugger.py", line 1246, in run_on_thread + self.schedule_work(lambda : self.run_locally(text, cur_frame, execution_id, frame_kind, repr_kind)) + File ".../visualstudio_py_debugger.py", line 1238, in schedule_work + self.unblock() + File ".../visualstudio_py_debugger.py", line 1234, in unblock + self._block_lock.release() + RuntimeError: release unlocked lock + ``` + +## Next steps + +- [Python environments](/docs/python/environments.md) - Control which Python interpreter is used for editing and debugging. +- [Unit testing](/docs/python/unit-testing.md) - Configure unit test environments and discover, run, and debug tests. +- [Settings reference](/docs/python/settings-reference.md) - Explore the full range of Python-related settings in VS Code. +- [General debugging](/docs/editor/debugging.md) - Learn about the debugging features of VS Code. diff --git a/docs/python/editing.md b/docs/python/editing.md new file mode 100644 index 0000000000000000000000000000000000000000..305542b2ab44be20427ee1c3635751f181fb15f6 --- /dev/null +++ b/docs/python/editing.md @@ -0,0 +1,198 @@ +--- +Order: 2 +Area: python +TOCTitle: Editing Code +ContentId: 0ccb0e35-c4b2-4001-91bf-79ff1618f601 +PageTitle: Editing Python Code in Visual Studio Code +DateApproved: 01/29/2019 +MetaDescription: Editing Python in Visual Studio Code +MetaSocialImage: images/tutorial/social.png +--- +# Editing Python in Visual Studio Code + +The Python extension provides many features for editing Python source code in Visual Studio Code: + +- [Autocomplete and IntelliSense](#autocomplete-and-intellisense) +- [Run Selection/Line in Terminal (REPL)](#run-selectionline-in-terminal-repl) +- [Formatting](#formatting) +- [Refactoring](#refactoring) + +Also see [Linting](/docs/python/linting.md) and [Jupyter Support](/docs/python/jupyter-support.md). + +## Autocomplete and IntelliSense + +Autocomplete and IntelliSense are provided for all files within the current working folder and for Python packages that are installed in standard locations. To customize the behavior of the analysis engine, see the [code analysis settings](settings-reference.md#code-analysis-settings) and [autocomplete settings](settings-reference.md#autocomplete-settings). + +You can also customize the general behavior of autocomplete and IntelliSense, even to disable these features entirely. See [Customizing IntelliSense](/docs/editor/intellisense.md#customizing-intellisense). + +![IntelliSense and autocomplete for Python code](images/editing/python-editing.gif) + +> **Tip**: Check out the [IntelliCode extension for VS Code (preview)](https://go.microsoft.com/fwlink/?linkid=2006060). IntelliCode provides a set of AI-assisted capabilities for IntelliSense in Python, such as inferring the most relevant auto-completions based on the current code context. For more information, see the [IntelliCode for VS Code FAQ](https://docs.microsoft.com/visualstudio/intellicode/intellicode-visual-studio-code). + +### Enable IntelliSense for custom package locations + +To enable IntelliSense for packages that are installed in other, non-standard locations, add those locations to the `python.autoComplete.extraPaths` collection in the settings file (the default collection is empty). For example, you might have installed Google App Engine installed in custom locations, specified in `app.yaml` if you use Flask. In this case you'd specify those locations as follows: + +**Windows:** + +```json +"python.autoComplete.extraPaths": [ + "C:/Program Files (x86)/Google/google_appengine", + "C:/Program Files (x86)/Google/google_appengine/lib/flask-0.12"] +``` + +**macOS/Linux:** + +```json +"python.autoComplete.extraPaths": [ + "~/.local/lib/Google/google_appengine", + "~/.local/lib/Google/google_appengine/lib/flask-0.12" ] +``` + +The `python.autocomplete.addBrackets` setting (default `false`) also determines whether VS Code automatically adds parentheses (`()`) when autocompleting a function name. For example, if you set `addBrackets` to `true`: + +```json + "python.autoComplete.addBrackets": true, +``` + +and then write `import os` followed by `os.getc`, you'll see autocomplete for `os.getcwd`. Selecting that auto-complete adds `os.getcwd()` to your source code and place the cursor inside the parentheses. When the setting is false, only `os.getcwd` is added to the file. + +For more on IntelliSense generally, see [IntelliSense](/docs/editor/intellisense.md). + +### Troubleshooting + +If autocomplete and IntelliSense are not working for a custom module, check the following causes: + +| Cause | Solution | +| --- | --- | +| The path to the python interpreter is incorrect | Check the `pythonPath` setting. Restart VS Code if you make a correction. | +| The custom module is located in a non-standard location (not installed using pip). | Add the location to the `python.autoComplete.extraPaths` setting and restart VS Code. | +| VS Code was not launched from the active virtual environment that would set the path to custom modules. | Launch VS Code from a command prompt with the correct virtual environment activated, for example: `(venv) terminal:~$ code`. | + +## Run Selection/Line in Terminal (REPL) + +The **Python: Run Selection/Line in Python Terminal** command (`kbstyle(Shift+Enter)`) is a simple way to take whatever code is selected, or the code on the current line if there is no selection, and run it in the Python Terminal. An identical **Run Selection/Line in Python Terminal** command is also available on the context menu for a selection in the editor. + +Source code that runs in the terminal/REPL is cumulative until the current instance of the terminal is closed. + +The command opens the Python Terminal if necessary; you can also open the interactive REPL environment directly using the **Python: Start REPL** command. (Initial startup might take a few moments especially if the first statement you run is an `import`.) + +On first use of the **Python: Run Selection/Line in Python Terminal** command, VS Code may send the text to the REPL before that environment is ready, in which case the selection or line is not run. If you encounter this behavior, try the command again when the REPL has finished loading. + +> **Note**: At present, using `kbstyle(Shift+Enter)` keeps the editor on the same line of source code. [Issue 480](https://github.com/Microsoft/vscode-python/issues/480) discusses automatically moving to the next line. + +## Formatting + +Formatting makes code easier to read by human beings by applying specific rules and conventions for line spacing, indents, spacing around operators, and so on (see an example on the [autopep8](https://pypi.org/project/autopep8/) page). Formatting doesn't affect the functionality of the code itself. ([Linting](/docs/python/linting.md), on the other hand, analyzes code for common syntactical, stylistic, and functional errors as well as unconventional programming practices that can lead to errors. Although there is a little overlap between formatting and linting, the two capabilities are complementary.) + +The Python extension supports source code formatting using either [autopep8](https://pypi.org/project/autopep8/) (the default), [black](https://github.com/ambv/black), or [yapf](https://github.com/google/yapf). + +### General formatting settings + +| Setting
(python.formatting.) | Default value | Description | +| --- | --- | --- | +| provider | `"autopep8"` | Specifies the formatter to use, either "autopep8", "yapf", or "black". | + +### Formatter-specific settings + +The following settings apply to the individual formatters. The Python extension looks in the current `pythonPath` for the formatter. To use a formatter in another location, specify that location in the appropriate custom path setting. The `pip install` commands may require elevation. + +| Formatter | Install steps | Arguments setting
(python.formatting.) | Custom path setting
(python.formatting.) | +| --- | --- | --- | --- | +| autopep8 | pip install pep8
pip install --upgrade autopep8 | autopep8Args | autopep8Path | +| black (see note) | pip install black | blackArgs | blackPath | +| yapf | pip install yapf | yapfArgs | yapfPath | + +> **Note**: By default, the Black formatter can't be installed when a Python 2 environment is active. Attempting to do so may display the message "Formatter black is not installed. Install?". If you try to install Black in response, another message appears saying "Could not find a version that satisfies the requirement black' No matching distribution found for black." +> +> To work around this issue and use the Black formatter with Python 2, first install Black in a Python 3 environment. Then set the `python.formatting.blackPath` setting to that install location. + +When using custom arguments, each top-level element of an argument string that's separated by space on the command line must be a separate item in the args list. For example: + +```json +"python.formatting.autopep8Args": ["--max-line-length", "120", "--experimental"], +"python.formatting.yapfArgs": ["--style", "{based_on_style: chromium, indent_width: 20}"] +"python.formatting.blackArgs": ["--line-length", "100"] +``` + +In the second example, the top-level element `{based_on_style: chromium, indent_width: 20}` is a single value contained in braces, so the spaces within that value don't delineate a separate element. + +### Troubleshooting + +If formatting fails, check the following possible causes: + +| Cause | Solution | +| --- | --- | +| The path to the python interpreter is incorrect. | Check the `pythonPath` setting. | +| The formatter is not installed in the current environment. | Open a command prompt, navigate to the location specified in the `pythonPath` setting, and run `pip install` for the formatter. +| The path to the formatter is incorrect. | Check the value of the appropriate `python.formatting.Path` setting. | +| Custom arguments for the formatter are incorrect. | Check that the appropriate `python.formatting.Path` setting does not contain arguments, and that `python.formatting.Args` contains a list of individual top-level argument elements such as `"python.formatting.yapfArgs": ["--style", "{based_on_style: chromium, indent_width: 20}"]`. + +When using the black formatter, VS Code issues the following warning when pasting source code into the editor: **Black does not support the "Format Select" command.** + +To prevent this warning, add the following entry to your user or workspace settings to disable format on paste for Python files: + +```json +"[python]": { + "editor.formatOnPaste": false +} +``` + +## Refactoring + +The Python extension adds the following refactoring commands: **Extract Variable**, **Extract Method**, and **Sort Imports**. + +### Extract Variable + +Extracts all similar occurrences of the selected text within the current scope, and replaces it with a variable. The new method is given the name `newvariableNNN` where NNN is a random number. + +Invoked by: + +- Context Menu: right-click a selection and select **Extract Variable**. +- Command Palette (`kb(workbench.action.showCommands)`), then **Python Refactor: Extract Variable**. +- Assign a keyboard shortcut to the `python.refactorExtractVariable` command. + +![Refactoring a variable](images/editing/refactorExtractVar.gif) + +### Extract Method + +Extracts all similar occurrences of the selected expression or block of within the current scope, and replaces it with a method call. The new method is given the name `newmethodNNN` where NNN is a random number. + +Invoked by: + +- Context Menu: right-click a selection and select **Extract Method**. +- Command Palette (`kb(workbench.action.showCommands)`), then **Python Refactor: Extract Method**. +- Assign a keyboard shortcut to the `python.refactorExtractMethod` command. + +![Refactoring code into a method](images/editing/refactorExtractMethod.gif) + +### Sort Imports + +Sort Imports uses the isort package to consolidate specific imports from the same module into a single `import` statement and to organize `import` statements in alphabetical order. + +Invoked by: + +- Right-click in editor and select **Sort Imports** (no selection is required) +- Command Palette (`kb(workbench.action.showCommands)`), then **Python Refactor: Sort Imports** +- Assign a keyboard shortcut to the `python.sortImports` command + +![Sorting import statements](images/editing/sortImports.gif) + +Custom arguments to isort are specified in the `python.sortImports.args` setting, where each top-level element, as separated by spaces on the command line, is a separate item in the array: + +```json +"python.sortImports.args": ["-rc", "--atomic"], +``` + +To use a custom isort script, use the `python.sortImports.path` setting to specify the path: + +Further configurations can be stored in an `.isort.cfg` file as documented on [Configuring isort](https://github.com/timothycrosley/isort#configuring-isort). + +## Next steps + +- [Linting](/docs/python/linting.md) - Enable, configure, and apply a variety of Python linters. +- [Debugging](/docs/python/debugging.md) - Learn to debug Python both locally and remotely. +- [Unit testing](/docs/python/unit-testing.md) - Configure unit test environments and discover, run, and debug tests. +- [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +- [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +- [IntelliSense](/docs/editor/intellisense.md) - Learn about IntelliSense features. diff --git a/docs/python/environments.md b/docs/python/environments.md new file mode 100644 index 0000000000000000000000000000000000000000..2ba44636e0e7b8f56426b18b90a3c13c1645f9a0 --- /dev/null +++ b/docs/python/environments.md @@ -0,0 +1,261 @@ +--- +Order: 6 +Area: python +TOCTitle: Environments +ContentId: 8fe4ca8b-fc70-4216-86c7-2c11b6c14cc6 +PageTitle: Using Python Environments in Visual Studio Code +DateApproved: 01/17/2019 +MetaDescription: Configuring Python Environments in Visual Studio Code +MetaSocialImage: images/tutorial/social.png +--- +# Using Python environments in VS Code + +An "environment" in Python is the context in which a Python program runs. An environment consists of an interpreter and any number of installed packages. The Python extension for VS Code provides helpful integration features for working with different environments. + +> **Note**: If you're looking to get started with Python in Visual Studio Code, refer to the tutorial [Getting Started with Python in VS Code](/docs/python/python-tutorial.md). + +## Select and activate an environment + +By default, the Python extension looks for and uses the first Python interpreter it finds in the system path. If it doesn't find an interpreter, it issues a warning. On macOS, the extension also issues a warning if you're using the OS-installed Python interpreter, because you typically want to use an interpreter you install directly. In either case, you can disable these warnings by setting `python.disableInstallationCheck` to `true` in your user [settings](/docs/getstarted/settings.md). + +To select a specific environment, use the **Python: Select Interpreter** command from the **Command Palette** (`kb(workbench.action.showCommands)`). + +![Python: Select Interpreter command](images/environments/select-interpreters-command.png) + +You can switch environments at any time; switching environments helps you test different parts of your project with different interpreters or library versions as needed. + +The **Python: Select Interpreter** command displays a list of available global environments, conda environments, and virtual environments. (See the [Where the extension looks for environments](#where-the-extension-looks-for-environments) section for details, including the distinctions between these types of environments.) The following image, for example, shows several Anaconda and CPython installations along with a conda environment and a virtual environment (`env`) that's located within the workspace folder: + +![List of interpreters](images/environments/interpreters-list.png) + +> **Note:** On Windows, it can take a little time for VS Code to detect available conda environments. During that process, you may see "(cached)" before the path to an environment. The label indicates that VS Code is presently working with cached information for that environment. + +Selecting an interpreter from the list adds an entry for `python.pythonPath` with the path to the interpreter inside your [Workspace Settings](/docs/getstarted/settings.md). Because the path is part of the workspace settings, the same environment should already be selected whenever you open that workspace. + +The Python extension uses the selected environment for running Python code (using the **Python: Run Python File in Terminal** command), providing language services (auto-complete, syntax checking, linting, formatting, etc.) when you have a `.py` file open in the editor, and opening a terminal with the **Terminal: Create New Integrated Terminal** command. In the latter case, VS Code automatically activated the selected environment. + +> **Tip**: To prevent automatic activation of a selected environment, add `"python.terminal.activateEnvironment": false` to your `settings.json` file (it can be placed anywhere as a sibling to the existing settings). + +> **Note**: By default, VS Code uses the interpreter identified by `python:pythonPath` setting when debugging code. You can override this behavior by specifying a different path in the `pythonPath` property of a debug configuration. See [Choose a debugging environment](#choose-a-debugging-environment). + +The Status Bar always shows the current interpreter. + +![Status Bar showing a selected interpreter](images/environments/selected-interpreter-status-bar.png) + +The Status Bar also reflects when no interpreter is selected. + +![No interpreter selected](images/environments/no-interpreter-selected-statusbar.png) + +In either case, clicking this area of the Status Bar is a convenient shortcut for the **Python: Select Interpreter** command. + +> **Tip**: If you have any problems with VS Code recognizing a virtual environment, please [file an issue](https://github.com/Microsoft/vscode-docs/issues) in the documentation repository so we can help determine the cause. + +### Environments and Terminal windows + +After using **Python: Select Interpreter**, that interpreter is applied when right-clicking a file and selecting **Python: Run Python File in Terminal**. The environment is also activated automatically when you use the **Terminal: Create New Integrated Terminal** command unless you change the `python.terminal.activateEnvironment` setting to `false`. + +However, launching VS Code from a shell in which a certain Python environment is activated does not automatically activate that environment in the default integrated terminal. Use the **Terminal: Create New Integrated Terminal** command after VS Code is running. + +> **Note:** conda environments cannot be automatically activated in the integrated terminal if PowerShell is set as the integrated shell. See [Integrated terminal - Configuration](/docs/editor/integrated-terminal.md#configuration) for how to change the shell. + +Any changes you make to an activated environment within the terminal are persistent. For example, using `conda install ` from the terminal with a conda environment activated installs the package into that environment permanently. Similarly, using `pip install` in a terminal with a virtual environment activated adds the package to that environment. + +Changing interpreters with the **Python: Select Interpreter** command doesn't affect terminal panels that are already open. You can thus activate separate environments in a split terminal: select the first interpreter, create a terminal for it, select a different interpreter, then use the split button (`kb(workbench.action.terminal.split)`) in the terminal title bar. + +### Choose a debugging environment + +By default, the `python.pythonPath` setting specifies the Python interpreter to use for debugging. However, if you have a `pythonPath` property in the debug configuration of `launch.json`, that interpreter is used instead. To be more specific, VS Code applies the following order of precedence when determining which interpreter to use for debugging: + +1. `pythonPath` property of the selected debug configuration in `launch.json` +1. `python.pythonPath` setting in the workspace `settings.json` +1. `python.pythonPath` setting in the user `settings.json` + +For more details on debug configuration, see [Debugging configurations](/docs/python/debugging.md). + +## Where the extension looks for environments + +The extension automatically looks for interpreters in the following locations: + +- Standard install paths such as `/usr/local/bin`, `/usr/sbin`, `/sbin`, `c:\\python27`, `c:\\python36`, etc. +- Virtual environments located directly under the workspace (project) folder. +- Virtual environments located in the folder identified by the `python.venvPath` setting (see [General settings](/docs/python/settings-reference.md#general-settings)), which can contain multiple virtual environments. The extension looks for virtual environments in the first-level subfolders of `venvPath`. +- Interpreters installed by [pyenv](https://github.com/pyenv/pyenv). +- A [pipenv](https://docs.pipenv.org/) environment for the workplace folder. If one is found, then no other interpreters are searched for or listed as pipenv expects to manage all aspects of the environment. +- Conda environments that contain a Python interpreter. VS Code does not show conda environments that don't contain an interpreter. +- Interpreters installed in a `.direnv` folder for [direnv](https://direnv.net/) under the workspace (project) folder. + +You can also [manually specify an interpreter](#manually-specify-an-interpreter) if Visual Studio Code does not locate it automatically. + +The extension also loads an [environment variable definitions file](#environment-variable-definitions-file) identified by the `python.envFile` setting. The default value of this setting is `${workspaceFolder}/.env`. + +### Global, virtual, and conda environments + +By default, any Python interpreter that you've installed run in its own **global environment**, which is not specific to any one project. For example, if you just run `python` (Windows) or `python3` (macOS/Linux) at a new command prompt, you're running in that interpreter's global environment. Accordingly, any packages that you install or uninstall affect the global environment and all programs that you run within that context. + +> **Note**: The Python Extension version 2018.8.1 and later automatically updates environments. + +Although working in the global environment is an easy way to get started, that environment will, over time, become cluttered with many different packages that you've installed for different projects. Such clutter makes it difficult to thoroughly test an application against a specific set of packages with known versions, which is exactly the kind of environment you'd set up on a build server or web server. + +For this reason, developers often create a **virtual environment** for a project. A virtual environment is a subfolder in a project that contains a copy of a specific interpreter. When you activate the virtual environment, any packages you install are installed only in that environment's subfolder. When you then run a Python program within that environment, you know that it's running against only those specific packages. + +> **Tip**: A **conda environment** is a virtual environments that's created and managed using the `conda` package manager. See [Conda environments](conda-environments) for more details. + +To create a virtual environment, use the following command, where ".venv" is the name of the environment folder: + +```bash +# macOS/Linux +# You may need to run sudo apt-get install python3-venv first +python3 -m venv .venv + +# Windows +# You can also use py -3 -m venv .venv +python -m venv .venv +``` + +For examples of using virtual environment in projects, see the [Django tutorial](/docs/python/tutorial-django.md) and the [Flask tutorial](/docs/python/tutorial-flask.md). + +> **Note**: If you're using a version of the Python extension prior to 2018.10, and you create a virtual environment in a VS Code terminal, you must run the **Reload Window** command from the Command Palette and then use **Python: Select Interpreter** to activate the environment. If you have any problems with VS Code recognizing a virtual environment, please [file an issue](https://github.com/Microsoft/vscode-docs/issues) in the documentation repository so we can help determine the cause. + +> **Tip**: When you're ready to deploy the application to other computers, you can create a `requirements.txt` file with the command `pip freeze > requirements.txt` (`pip3` on macOS/Linux). The requirements file describes the packages you've installed in your virtual environment. With only this file, you or other developers can restore those packages using `pip install -r requirements.txt` (or, again, `pip3` on macOS/Linux). By using a requirements file, you need not commit the virtual environment itself to source control. + +### Conda environments + +A conda environment is a Python environment that's managed using the `conda` package manager (see [Getting started with conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html) (conda.io)). Conda works well to create environments with interrelated dependencies as well as binary packages. Unlike virtual environments, which are scoped to a project, conda environments are available globally on any given computer. This availability makes it easy to configure several distinct conda environments and then choose the appropriate one for any given project. + +As noted earlier, the Python extension automatically detects existing conda environments provided that the environment contains a Python interpreter. For example, the following command creates a conda environment with the Python 3.4 interpreter and several libraries, which VS Code then shows in the list of available interpreters: + +```bash +conda create -n env-01 python=3.4 scipy=0.15.0 astroid babel +``` + +> **Tip:** If you create a new conda environment while VS Code is running, use the **Reload Window** command to refresh the environment list shown with **Python: Select Interpreter**; otherwise you may not see the environment there. It might take a short time to appear; if you don't see it at first, wait 15 seconds then try using the command again. + +In contrast, if you fail to specify an interpreter as with `conda create --name env-00`, the environment won't appear in the list. + +For more information on the conda command line, see [Conda environments](https://conda.io/docs/user-guide/tasks/manage-environments.html) (conda.io). + +> **Note:** Although the Python extension for VS Code doesn't currently have direct integration with conda environment.yml files, VS Code itself is a great YAML editor. + +### Manually specify an interpreter + +If VS Code does not automatically locate an interpreter you want to use, you can set the path to it manually in your Workspace Settings `settings.json` file. With any of the entries that follow, you can just add the line as a sibling to other existing settings.) + +First, select the **File** (**Code** on macOS) > **Preferences** > **Settings** menu command (`kb(workbench.action.openSettings)`) to open your [Settings](/docs/getstarted/settings.md), select **Workspace**. + +Then do any of the following steps: + +1. Create or modify an entry for `python.pythonPath` with the full path to the Python executable (if you edit `settings.json` directly, add the line below as the setting ): + + For example: + + - Windows: + + ```json + "python.pythonPath": "c:/python36/python.exe", + ``` + + - macOS/Linux: + + ```json + "python.pythonPath": "/home/python36/python", + ``` + +1. You can also use `python.pythonPath` to point to a virtual environment, for example: + + Windows: + + ```json + "python.pythonPath": "c:/dev/ala/venv/Scripts/python.exe", + ``` + + macOS/Linux: + + ```json + "python.pythonPath": "/home/abc/dev/ala/venv/bin/python", + ``` + +1. You can use an environment variable in the path setting using the syntax `${env:VARIABLE}`. For example, if you've created a variable named `PYTHON_INSTALL_LOC` with a path to an interpreter, you can then use the following setting value: + + ```json + "python.pythonPath": "${env:PYTHON_INSTALL_LOC}", + ``` + + By using an environment variable, you can easily transfer a project between operating systems where the paths are different, just be sure to set the environment variable on the operating system first. + +## Environment variable definitions file + +An environment variable definitions file is a simple text file containing key-value pairs in the form of `environment_variable=value`, with `#` used for comments. Multiline values are not supported, but values can refer to any other environment variable that's already defined in the system or earlier in the file. For more information, see [Variable substitution](#variable-substitution). + +By default, the Python extension looks for and loads a file named `.env` in the current workspace folder, then applies those definitions. The file is identified by the default entry `"python.envFile": "${workspaceFolder}/.env"` in your user settings (see [General settings](/docs/python/settings-reference.md#general-settings)). You can change the `python.envFile` setting at any time to use a different definitions file. + +A debug configuration also contains an `envFile` property that also defaults to the `.env` file in the current workspace (see [Debugging - Set configuration options](/docs/python/debugging.md#set-configuration-options)). This property allows you to easily set variables for debugging purposes that replace variables specified in the default `.env` file. + +For example, when developing a web application, you might want to easily switch between development and production servers. Instead of coding the different URLs and other settings into your application directly, you could use separate definitions files for each. For example: + +**dev.env file** + +```bash +# dev.env - development configuration + +# API endpoint +MYPROJECT_APIENDPOINT=https://my.domain.com/api/dev/ + +# Variables for the database +MYPROJECT_DBURL=https://my.domain.com/db/dev +MYPROJECT_DBUSER=devadmin +MYPROJECT_DBPASSWORD=!dfka**213= +``` + +**prod.env file** + +```bash +# prod.env - production configuration + +# API endpoint +MYPROJECT_APIENDPOINT=https://my.domain.com/api/ + +# Variables for the database +MYPROJECT_DBURL=https://my.domain.com/db/ +MYPROJECT_DBUSER=coreuser +MYPROJECT_DBPASSWORD=kKKfa98*11@ +``` + +You can then set the `python.envFile` setting to `${workspaceFolder}/prod.env`, then set the `envFile` property in the debug configuration to `${workspaceFolder}/dev.env`. + +### Variable substitution + +When defining an environment variables in a definitions file, you can use the value of any existing environment variable with the following general syntax: + +```bash +=...${EXISTING_VARIABLE}... +``` + +where `...` means any other text as used in the value. The curly braces are required. + +Within this syntax, the following rules apply: + +- Variables are processed in the order they appear in the `.env` file, so you can use any variable that's defined earlier in the file. +- Single or double quotes don't affect substituted value and are included in the defined value. For example, if the value of `VAR1` is `abcedfg`, then `VAR2='${OTHERVAR}'` assigns the value `'abcedfg'` to `VAR2`. +- The `$` character can be escaped with a backslash, as in `\$`. +- You can use recursive substitution, such as `PYTHONPATH=${PROJ_DIR}:${PYTHONPATH}` (where `PROJ_DIR` is any other environment variable). +- You can use only simple substitution; nesting such as `${_${OTHERVAR}_EX}` is not supported. +- Entries with unsupported syntax are left as-is. + +## Use of the PYTHONPATH variable + +The [PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH) environment variable specifies additional locations where the Python interpreter should look for modules. The value of PYTHONPATH can contain multiple path values separated by `os.pathsep` (semicolons on Windows, colons on Linux/macOS). Invalid paths are ignored. + +> **Note**: you must set the PYTHONPATH variable through your operating system as VS Code doesn't provide a means to set environment variables directly. + +In VS Code, PYTHONPATH affects debugging, linting, IntelliSense, unit testing, and any other operation that depends on Python resolving modules. For example, suppose you have source code in a `src` folder and tests in a `tests` folder. When running tests, however, they can't normally access modules in `src` unless you hard-code relative paths. To solve this problem, add the path to `src` to PYTHONPATH. + +It's recommended that you set the PYTHONPATH variable in an [Environment variable definitions file](#environment-variable-definitions-file), described earlier. + +> **Note**: PYTHONPATH does **not**, repeat **not**, specify a path to a Python interpreter itself, and thus you **never** use it with the `python.pythonPath` setting. Clearly, the environment variable was badly named, but...[c'est la vie](https://www.dictionary.com/browse/c-est-la-vie). So make sure to read the [PYTHONPATH documentation](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH) several times and fix in your mind that PYTHONPATH is **not** a path to an interpreter. + +## Next steps + +- [Editing code](/docs/python/editing.md) - Learn about autocomplete, IntelliSense, formatting, and refactoring for Python. +- [Debugging](/docs/python/debugging.md) - Learn to debug Python both locally and remotely. +- [Unit testing](/docs/python/unit-testing.md) - Configure unit test environments and discover, run, and debug tests. +- [Settings reference](/docs/python/settings-reference.md) - Explore the full range of Python-related settings in VS Code. diff --git a/docs/python/images/debugging/add-configuration.png b/docs/python/images/debugging/add-configuration.png new file mode 100644 index 0000000000000000000000000000000000000000..a906b38c2c673df2482f265aeae462a3a29437e1 Binary files /dev/null and b/docs/python/images/debugging/add-configuration.png differ diff --git a/docs/python/images/debugging/debug-configurations.png b/docs/python/images/debugging/debug-configurations.png new file mode 100644 index 0000000000000000000000000000000000000000..3d2cabc41d7e92df6fd9db2e7d02c74d020daf47 Binary files /dev/null and b/docs/python/images/debugging/debug-configurations.png differ diff --git a/docs/python/images/debugging/debug-icon.png b/docs/python/images/debugging/debug-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..60c1745fd186f7a62a0825883c03afbd51b5c8f9 Binary files /dev/null and b/docs/python/images/debugging/debug-icon.png differ diff --git a/docs/python/images/debugging/debug-settings-warning-icon.png b/docs/python/images/debugging/debug-settings-warning-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..6cd8c5ed3280cd650b762530400bdf36e0a0dcf6 Binary files /dev/null and b/docs/python/images/debugging/debug-settings-warning-icon.png differ diff --git a/docs/python/images/debugging/debug-settings.png b/docs/python/images/debugging/debug-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..d1530ecf49eb0c3d9cdb1c03fbda63383d88f45d Binary files /dev/null and b/docs/python/images/debugging/debug-settings.png differ diff --git a/docs/python/images/debugging/debug-status-bar.png b/docs/python/images/debugging/debug-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..5c2f27f8e52252be516313cd90700ff763615373 Binary files /dev/null and b/docs/python/images/debugging/debug-status-bar.png differ diff --git a/docs/python/images/debugging/debugGAE.gif b/docs/python/images/debugging/debugGAE.gif new file mode 100644 index 0000000000000000000000000000000000000000..01de4774adc6f3164386f36e8dc2eaed2745b957 --- /dev/null +++ b/docs/python/images/debugging/debugGAE.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1b5939f8009674d0ba6bc5f2909d1956fcf90c439f45c6ace2a6f9d5505ae3ac +size 5146761 diff --git a/docs/python/images/debugging/remote-debug-toolbar.png b/docs/python/images/debugging/remote-debug-toolbar.png new file mode 100644 index 0000000000000000000000000000000000000000..d6c3452264cc55ec9ae431d3c4ddc5e71df4e730 Binary files /dev/null and b/docs/python/images/debugging/remote-debug-toolbar.png differ diff --git a/docs/python/images/debugging/select-configuration.png b/docs/python/images/debugging/select-configuration.png new file mode 100644 index 0000000000000000000000000000000000000000..8c2714c7da2ec0c6d8a41b250dcc1e1ca1d5014c Binary files /dev/null and b/docs/python/images/debugging/select-configuration.png differ diff --git a/docs/python/images/deploy-azure/app-service-create-new.png b/docs/python/images/deploy-azure/app-service-create-new.png new file mode 100644 index 0000000000000000000000000000000000000000..ab90fe43f74657557a601810455bfdd0e65dfa02 Binary files /dev/null and b/docs/python/images/deploy-azure/app-service-create-new.png differ diff --git a/docs/python/images/deploy-azure/app-service-created.png b/docs/python/images/deploy-azure/app-service-created.png new file mode 100644 index 0000000000000000000000000000000000000000..74a49722e787f0aabde38f932bac01a9544dc2a2 Binary files /dev/null and b/docs/python/images/deploy-azure/app-service-created.png differ diff --git a/docs/python/images/deploy-azure/app-service-output.png b/docs/python/images/deploy-azure/app-service-output.png new file mode 100644 index 0000000000000000000000000000000000000000..fff9bcc522c51dd78294a698b651c4b743002374 Binary files /dev/null and b/docs/python/images/deploy-azure/app-service-output.png differ diff --git a/docs/python/images/deploy-azure/azure-account-status-bar.png b/docs/python/images/deploy-azure/azure-account-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..4167e7f35d00f0d70c4228d541d274f7ea387b3f Binary files /dev/null and b/docs/python/images/deploy-azure/azure-account-status-bar.png differ diff --git a/docs/python/images/deploy-azure/azure-portal-startup-file.png b/docs/python/images/deploy-azure/azure-portal-startup-file.png new file mode 100644 index 0000000000000000000000000000000000000000..9362312428e9d44b87f7f309d78b3b74e0b79cd1 Binary files /dev/null and b/docs/python/images/deploy-azure/azure-portal-startup-file.png differ diff --git a/docs/python/images/deploy-azure/azure-sign-in.png b/docs/python/images/deploy-azure/azure-sign-in.png new file mode 100644 index 0000000000000000000000000000000000000000..49eab0c796fa6b1462266bd23790ed4009ebf50c Binary files /dev/null and b/docs/python/images/deploy-azure/azure-sign-in.png differ diff --git a/docs/python/images/deploy-azure/azure-subscription-view.png b/docs/python/images/deploy-azure/azure-subscription-view.png new file mode 100644 index 0000000000000000000000000000000000000000..a44c66350f60b77c62a1a23ff787fd872fe5e7e9 Binary files /dev/null and b/docs/python/images/deploy-azure/azure-subscription-view.png differ diff --git a/docs/python/images/deploy-azure/browse-website-command.png b/docs/python/images/deploy-azure/browse-website-command.png new file mode 100644 index 0000000000000000000000000000000000000000..ca4b029527556e4bda9e3a90cd77d4e5300ea092 Binary files /dev/null and b/docs/python/images/deploy-azure/browse-website-command.png differ diff --git a/docs/python/images/deploy-azure/configure-deployment-source.png b/docs/python/images/deploy-azure/configure-deployment-source.png new file mode 100644 index 0000000000000000000000000000000000000000..f1eb52943baf38d522243198fc4ec9c028c5fbd1 Binary files /dev/null and b/docs/python/images/deploy-azure/configure-deployment-source.png differ diff --git a/docs/python/images/deploy-azure/default-python-app.png b/docs/python/images/deploy-azure/default-python-app.png new file mode 100644 index 0000000000000000000000000000000000000000..58f703fc04a5907ebfbef03bab196162b0444cb4 Binary files /dev/null and b/docs/python/images/deploy-azure/default-python-app.png differ diff --git a/docs/python/images/deploy-azure/deploy-to-web-app-command.png b/docs/python/images/deploy-azure/deploy-to-web-app-command.png new file mode 100644 index 0000000000000000000000000000000000000000..f296612ebf72a4948a9b4ee35d1490b673b28484 Binary files /dev/null and b/docs/python/images/deploy-azure/deploy-to-web-app-command.png differ diff --git a/docs/python/images/deploy-azure/deployment-options-disconnect.png b/docs/python/images/deploy-azure/deployment-options-disconnect.png new file mode 100644 index 0000000000000000000000000000000000000000..d7a4e4f740fee32dff2153528e246d9fe139a776 Binary files /dev/null and b/docs/python/images/deploy-azure/deployment-options-disconnect.png differ diff --git a/docs/python/images/deploy-azure/deployment-options-status.png b/docs/python/images/deploy-azure/deployment-options-status.png new file mode 100644 index 0000000000000000000000000000000000000000..aa590cc3db6793a70e8f143546870dff12c43314 Binary files /dev/null and b/docs/python/images/deploy-azure/deployment-options-status.png differ diff --git a/docs/python/images/deploy-azure/deployment-underway.png b/docs/python/images/deploy-azure/deployment-underway.png new file mode 100644 index 0000000000000000000000000000000000000000..16e5c6aac811c9e1ac4ef804246b05395f7104cc Binary files /dev/null and b/docs/python/images/deploy-azure/deployment-underway.png differ diff --git a/docs/python/images/deploy-azure/expand-files-node.png b/docs/python/images/deploy-azure/expand-files-node.png new file mode 100644 index 0000000000000000000000000000000000000000..6dbe8c438f6dd19b83c9d77e087bc4ca11b1a268 Binary files /dev/null and b/docs/python/images/deploy-azure/expand-files-node.png differ diff --git a/docs/python/images/deploy-azure/git-sync-changes.png b/docs/python/images/deploy-azure/git-sync-changes.png new file mode 100644 index 0000000000000000000000000000000000000000..a20f2cc8b6e5621c2a700fb89c463d4f213ba61d Binary files /dev/null and b/docs/python/images/deploy-azure/git-sync-changes.png differ diff --git a/docs/python/images/deploy-azure/github-access-warning.png b/docs/python/images/deploy-azure/github-access-warning.png new file mode 100644 index 0000000000000000000000000000000000000000..33beb4a706ecd73167f081f6f40373a54799b959 Binary files /dev/null and b/docs/python/images/deploy-azure/github-access-warning.png differ diff --git a/docs/python/images/deploy-azure/open-in-portal-command.png b/docs/python/images/deploy-azure/open-in-portal-command.png new file mode 100644 index 0000000000000000000000000000000000000000..873a6b42a7a38db7ea51990e83a17971f1099844 Binary files /dev/null and b/docs/python/images/deploy-azure/open-in-portal-command.png differ diff --git a/docs/python/images/deploy-azure/open-settings-in-portal-command.png b/docs/python/images/deploy-azure/open-settings-in-portal-command.png new file mode 100644 index 0000000000000000000000000000000000000000..7aef48bedcef0a8350de4dece7ccf5ea6e4802d5 Binary files /dev/null and b/docs/python/images/deploy-azure/open-settings-in-portal-command.png differ diff --git a/docs/python/images/deploy-azure/running-app.png b/docs/python/images/deploy-azure/running-app.png new file mode 100644 index 0000000000000000000000000000000000000000..2645a58eeb726e2cd59b5bdb06053ea7d9e2c954 Binary files /dev/null and b/docs/python/images/deploy-azure/running-app.png differ diff --git a/docs/python/images/deploy-azure/source-control-commit.png b/docs/python/images/deploy-azure/source-control-commit.png new file mode 100644 index 0000000000000000000000000000000000000000..28ba8da5d9caefb3160a45ce002a99b67a4390ee Binary files /dev/null and b/docs/python/images/deploy-azure/source-control-commit.png differ diff --git a/docs/python/images/deploy-azure/source-control-initialize-repository-button.png b/docs/python/images/deploy-azure/source-control-initialize-repository-button.png new file mode 100644 index 0000000000000000000000000000000000000000..58fecfbf14a94878a013fcdc1d628c77707a5fcd Binary files /dev/null and b/docs/python/images/deploy-azure/source-control-initialize-repository-button.png differ diff --git a/docs/python/images/deploy-azure/source-control-initialize-repository-command.png b/docs/python/images/deploy-azure/source-control-initialize-repository-command.png new file mode 100644 index 0000000000000000000000000000000000000000..555a5f065feb976157d039a659f4bc2fa0b6966e Binary files /dev/null and b/docs/python/images/deploy-azure/source-control-initialize-repository-command.png differ diff --git a/docs/python/images/deploy-azure/source-control-open-repository.png b/docs/python/images/deploy-azure/source-control-open-repository.png new file mode 100644 index 0000000000000000000000000000000000000000..f88639a6c4cdc8fc1b53f2db49a641d934a543cb Binary files /dev/null and b/docs/python/images/deploy-azure/source-control-open-repository.png differ diff --git a/docs/python/images/deploy-azure/source-control-select-folder.png b/docs/python/images/deploy-azure/source-control-select-folder.png new file mode 100644 index 0000000000000000000000000000000000000000..11cea0c59ad3b8b453a2a50eff1521bc9a8b0c31 Binary files /dev/null and b/docs/python/images/deploy-azure/source-control-select-folder.png differ diff --git a/docs/python/images/deploy-containers/add-app-service-setting.png b/docs/python/images/deploy-containers/add-app-service-setting.png new file mode 100644 index 0000000000000000000000000000000000000000..1b18b3a9cb87e4c45177df3e372c4c8154341fff Binary files /dev/null and b/docs/python/images/deploy-containers/add-app-service-setting.png differ diff --git a/docs/python/images/deploy-containers/azure-extensions.png b/docs/python/images/deploy-containers/azure-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..df42b50d35ba4c9681a2b5a5227c45de4e1c4156 Binary files /dev/null and b/docs/python/images/deploy-containers/azure-extensions.png differ diff --git a/docs/python/images/deploy-containers/deploy-find-image.png b/docs/python/images/deploy-containers/deploy-find-image.png new file mode 100644 index 0000000000000000000000000000000000000000..9b05335a3498291fa9c1aa80884b8f41799a6d05 Binary files /dev/null and b/docs/python/images/deploy-containers/deploy-find-image.png differ diff --git a/docs/python/images/deploy-containers/deploy-menu.png b/docs/python/images/deploy-containers/deploy-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..2be6ff7cb130f22b8b12ec44e095f4545cdbda8e Binary files /dev/null and b/docs/python/images/deploy-containers/deploy-menu.png differ diff --git a/docs/python/images/deploy-containers/deploy-to-app-service.gif b/docs/python/images/deploy-containers/deploy-to-app-service.gif new file mode 100644 index 0000000000000000000000000000000000000000..7e0c203759a5d7c5af3de6ae69cadf24bf13df5e --- /dev/null +++ b/docs/python/images/deploy-containers/deploy-to-app-service.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bbe2dc619de7ac3a2620b3ae486f6d466c8bc6a8dda47b0a0a4a2e1a4f9f4c41 +size 457941 diff --git a/docs/python/images/deploy-containers/image-in-acr.png b/docs/python/images/deploy-containers/image-in-acr.png new file mode 100644 index 0000000000000000000000000000000000000000..538588f4ed32e960132be3551d8d625806be8f3f Binary files /dev/null and b/docs/python/images/deploy-containers/image-in-acr.png differ diff --git a/docs/python/images/deploy-containers/image-list.png b/docs/python/images/deploy-containers/image-list.png new file mode 100644 index 0000000000000000000000000000000000000000..066be1aaf8f29e48154df3001b0c455a9a7483ac Binary files /dev/null and b/docs/python/images/deploy-containers/image-list.png differ diff --git a/docs/python/images/deploy-containers/manage-images.png b/docs/python/images/deploy-containers/manage-images.png new file mode 100644 index 0000000000000000000000000000000000000000..59135400f27f452471a22f2eb09962587104aadd Binary files /dev/null and b/docs/python/images/deploy-containers/manage-images.png differ diff --git a/docs/python/images/deploy-containers/registries.png b/docs/python/images/deploy-containers/registries.png new file mode 100644 index 0000000000000000000000000000000000000000..952d5e46ca1f58e66fc27256a0b137c1a33050f9 Binary files /dev/null and b/docs/python/images/deploy-containers/registries.png differ diff --git a/docs/python/images/deploy-containers/system-prune-command.png b/docs/python/images/deploy-containers/system-prune-command.png new file mode 100644 index 0000000000000000000000000000000000000000..845e77cd3002e9aeb55fe264818cb75ba1500406 Binary files /dev/null and b/docs/python/images/deploy-containers/system-prune-command.png differ diff --git a/docs/python/images/django-tutorial/app-in-browser-01.png b/docs/python/images/django-tutorial/app-in-browser-01.png new file mode 100644 index 0000000000000000000000000000000000000000..799be12d20f585f84dc5d7656330afc096532415 Binary files /dev/null and b/docs/python/images/django-tutorial/app-in-browser-01.png differ diff --git a/docs/python/images/django-tutorial/app-with-message-list.png b/docs/python/images/django-tutorial/app-with-message-list.png new file mode 100644 index 0000000000000000000000000000000000000000..b9adf59d0c64d0cc13c36c1b642b5552b9fb82df Binary files /dev/null and b/docs/python/images/django-tutorial/app-with-message-list.png differ diff --git a/docs/python/images/django-tutorial/autocomplete-for-code-snippet.png b/docs/python/images/django-tutorial/autocomplete-for-code-snippet.png new file mode 100644 index 0000000000000000000000000000000000000000..0fece5d8325af25486169fb07ca3b631c112bdac Binary files /dev/null and b/docs/python/images/django-tutorial/autocomplete-for-code-snippet.png differ diff --git a/docs/python/images/django-tutorial/code-snippet-inserted.png b/docs/python/images/django-tutorial/code-snippet-inserted.png new file mode 100644 index 0000000000000000000000000000000000000000..13bf9dbb1ff00ba050cd7427bfee3ef2f65dd7a4 Binary files /dev/null and b/docs/python/images/django-tutorial/code-snippet-inserted.png differ diff --git a/docs/python/images/django-tutorial/debug-breakpoint-set.png b/docs/python/images/django-tutorial/debug-breakpoint-set.png new file mode 100644 index 0000000000000000000000000000000000000000..0f03478e89855a1bf7a72c26c96d8fd6481bde85 Binary files /dev/null and b/docs/python/images/django-tutorial/debug-breakpoint-set.png differ diff --git a/docs/python/images/django-tutorial/debug-continue-arrow.png b/docs/python/images/django-tutorial/debug-continue-arrow.png new file mode 100644 index 0000000000000000000000000000000000000000..c244914f6cc57ff8585a9060f0a869dd82114d8b Binary files /dev/null and b/docs/python/images/django-tutorial/debug-continue-arrow.png differ diff --git a/docs/python/images/django-tutorial/debug-local-variables.png b/docs/python/images/django-tutorial/debug-local-variables.png new file mode 100644 index 0000000000000000000000000000000000000000..24539043a71782f3040c1685ce0f86ed063f7102 Binary files /dev/null and b/docs/python/images/django-tutorial/debug-local-variables.png differ diff --git a/docs/python/images/django-tutorial/debug-program-paused.png b/docs/python/images/django-tutorial/debug-program-paused.png new file mode 100644 index 0000000000000000000000000000000000000000..ef36264789d88c3d9d65506fb9ba1de782629163 Binary files /dev/null and b/docs/python/images/django-tutorial/debug-program-paused.png differ diff --git a/docs/python/images/django-tutorial/debug-run-result.png b/docs/python/images/django-tutorial/debug-run-result.png new file mode 100644 index 0000000000000000000000000000000000000000..6ca1dd91628ab02674eb4d63d4063faa7e20fa17 Binary files /dev/null and b/docs/python/images/django-tutorial/debug-run-result.png differ diff --git a/docs/python/images/django-tutorial/debug-select-configuration.png b/docs/python/images/django-tutorial/debug-select-configuration.png new file mode 100644 index 0000000000000000000000000000000000000000..cf66edd57308e42757e15fe5f7bcdb3f86c68e74 Binary files /dev/null and b/docs/python/images/django-tutorial/debug-select-configuration.png differ diff --git a/docs/python/images/django-tutorial/debug-status-bar.png b/docs/python/images/django-tutorial/debug-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..017ed6ac0872a903cbc4a4128f32897432ca6c77 Binary files /dev/null and b/docs/python/images/django-tutorial/debug-status-bar.png differ diff --git a/docs/python/images/django-tutorial/default-admin-interface.png b/docs/python/images/django-tutorial/default-admin-interface.png new file mode 100644 index 0000000000000000000000000000000000000000..d4b3235bf4e0e9632545f21d79a4a581c6345f9a Binary files /dev/null and b/docs/python/images/django-tutorial/default-admin-interface.png differ diff --git a/docs/python/images/django-tutorial/django-empty-project-success.png b/docs/python/images/django-tutorial/django-empty-project-success.png new file mode 100644 index 0000000000000000000000000000000000000000..9361f34b276e0857da767c501c2a2de79778efbe Binary files /dev/null and b/docs/python/images/django-tutorial/django-empty-project-success.png differ diff --git a/docs/python/images/django-tutorial/django-hello-app-success.png b/docs/python/images/django-tutorial/django-hello-app-success.png new file mode 100644 index 0000000000000000000000000000000000000000..799be12d20f585f84dc5d7656330afc096532415 Binary files /dev/null and b/docs/python/images/django-tutorial/django-hello-app-success.png differ diff --git a/docs/python/images/django-tutorial/full-app.png b/docs/python/images/django-tutorial/full-app.png new file mode 100644 index 0000000000000000000000000000000000000000..3af7132a9a3702e4a57ab4dd1adf345e6dba559e Binary files /dev/null and b/docs/python/images/django-tutorial/full-app.png differ diff --git a/docs/python/images/django-tutorial/login-prompt.png b/docs/python/images/django-tutorial/login-prompt.png new file mode 100644 index 0000000000000000000000000000000000000000..38578f3d410af8e73ccc527a6658dc737c0564e7 Binary files /dev/null and b/docs/python/images/django-tutorial/login-prompt.png differ diff --git a/docs/python/images/django-tutorial/message-logging-page.png b/docs/python/images/django-tutorial/message-logging-page.png new file mode 100644 index 0000000000000000000000000000000000000000..3e78df04ec6d018e3a6e65afade5e574b653955c Binary files /dev/null and b/docs/python/images/django-tutorial/message-logging-page.png differ diff --git a/docs/python/images/django-tutorial/peek-definition.png b/docs/python/images/django-tutorial/peek-definition.png new file mode 100644 index 0000000000000000000000000000000000000000..2bb3dd306178fea79382c1acb3db5d327f671465 Binary files /dev/null and b/docs/python/images/django-tutorial/peek-definition.png differ diff --git a/docs/python/images/django-tutorial/template-breakpoints.png b/docs/python/images/django-tutorial/template-breakpoints.png new file mode 100644 index 0000000000000000000000000000000000000000..8a33dea0d8190e636212cbc9266db0bdd2798edd Binary files /dev/null and b/docs/python/images/django-tutorial/template-breakpoints.png differ diff --git a/docs/python/images/django-tutorial/template-debugger.png b/docs/python/images/django-tutorial/template-debugger.png new file mode 100644 index 0000000000000000000000000000000000000000..f332a869c9cd5c6313e6841991f5dfb02fbc6db7 Binary files /dev/null and b/docs/python/images/django-tutorial/template-debugger.png differ diff --git a/docs/python/images/editing/python-editing.gif b/docs/python/images/editing/python-editing.gif new file mode 100644 index 0000000000000000000000000000000000000000..446342f5b479399d4ec60dbeb65f97e7fea055b6 --- /dev/null +++ b/docs/python/images/editing/python-editing.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:54550025e838173e979e79c9a8c931bb00e38aa2f1357dba40870531ec27cf16 +size 595936 diff --git a/docs/python/images/editing/refactorExtractMethod.gif b/docs/python/images/editing/refactorExtractMethod.gif new file mode 100644 index 0000000000000000000000000000000000000000..0b3c6926870ea5701e4cb816e324ef6b1f55bbd7 --- /dev/null +++ b/docs/python/images/editing/refactorExtractMethod.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:65840d2581a00986bf9843861777912cf5db2d71cb04d5bc9bda96373e3a0456 +size 122396 diff --git a/docs/python/images/editing/refactorExtractVar.gif b/docs/python/images/editing/refactorExtractVar.gif new file mode 100644 index 0000000000000000000000000000000000000000..d77558740028e1a7a671f32027e19acec0c68f20 Binary files /dev/null and b/docs/python/images/editing/refactorExtractVar.gif differ diff --git a/docs/python/images/editing/sortImports.gif b/docs/python/images/editing/sortImports.gif new file mode 100644 index 0000000000000000000000000000000000000000..6ea6bb13ecd2c9bde62ccab8fea358669ed5500d Binary files /dev/null and b/docs/python/images/editing/sortImports.gif differ diff --git a/docs/python/images/environments/interpreters-list.png b/docs/python/images/environments/interpreters-list.png new file mode 100644 index 0000000000000000000000000000000000000000..2cab3a48de39c11e5d63a98b6e743c73e05bf01d Binary files /dev/null and b/docs/python/images/environments/interpreters-list.png differ diff --git a/docs/python/images/environments/no-interpreter-selected-statusbar.png b/docs/python/images/environments/no-interpreter-selected-statusbar.png new file mode 100644 index 0000000000000000000000000000000000000000..acdfe1e14fba8a7e40c1b46ab9cb149bbf443b8f Binary files /dev/null and b/docs/python/images/environments/no-interpreter-selected-statusbar.png differ diff --git a/docs/python/images/environments/select-interpreters-command.png b/docs/python/images/environments/select-interpreters-command.png new file mode 100644 index 0000000000000000000000000000000000000000..8a357e05538384c72763b7c95d15d2414cfee833 Binary files /dev/null and b/docs/python/images/environments/select-interpreters-command.png differ diff --git a/docs/python/images/environments/selected-interpreter-status-bar.png b/docs/python/images/environments/selected-interpreter-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..7d56af7fef59c5de2a842522132107d363d09e1d Binary files /dev/null and b/docs/python/images/environments/selected-interpreter-status-bar.png differ diff --git a/docs/python/images/flask-tutorial/app-in-browser-01.png b/docs/python/images/flask-tutorial/app-in-browser-01.png new file mode 100644 index 0000000000000000000000000000000000000000..35bf16b0d518e7ff6d658a4388237dab51e23210 Binary files /dev/null and b/docs/python/images/flask-tutorial/app-in-browser-01.png differ diff --git a/docs/python/images/flask-tutorial/autocomplete-for-code-snippet.png b/docs/python/images/flask-tutorial/autocomplete-for-code-snippet.png new file mode 100644 index 0000000000000000000000000000000000000000..e86af6d3e64a78a893035452ba8eeb5b078567c7 Binary files /dev/null and b/docs/python/images/flask-tutorial/autocomplete-for-code-snippet.png differ diff --git a/docs/python/images/flask-tutorial/code-snippet-inserted.png b/docs/python/images/flask-tutorial/code-snippet-inserted.png new file mode 100644 index 0000000000000000000000000000000000000000..a225df8c88838808025521310dfbac755dd8683f Binary files /dev/null and b/docs/python/images/flask-tutorial/code-snippet-inserted.png differ diff --git a/docs/python/images/flask-tutorial/debug-breakpoint-set.png b/docs/python/images/flask-tutorial/debug-breakpoint-set.png new file mode 100644 index 0000000000000000000000000000000000000000..9410fc84056257280dc11e99febac35fa1dc5d26 Binary files /dev/null and b/docs/python/images/flask-tutorial/debug-breakpoint-set.png differ diff --git a/docs/python/images/flask-tutorial/debug-continue-arrow.png b/docs/python/images/flask-tutorial/debug-continue-arrow.png new file mode 100644 index 0000000000000000000000000000000000000000..0d16fe4ea896c4379b7ddb8a9f1659308323b628 Binary files /dev/null and b/docs/python/images/flask-tutorial/debug-continue-arrow.png differ diff --git a/docs/python/images/flask-tutorial/debug-local-variables.png b/docs/python/images/flask-tutorial/debug-local-variables.png new file mode 100644 index 0000000000000000000000000000000000000000..de5cadd30bd2d13b2e17d3113950cb575f2e0ef6 Binary files /dev/null and b/docs/python/images/flask-tutorial/debug-local-variables.png differ diff --git a/docs/python/images/flask-tutorial/debug-program-paused.png b/docs/python/images/flask-tutorial/debug-program-paused.png new file mode 100644 index 0000000000000000000000000000000000000000..ea3c7d8e9b38c67137f4caefb8977b13606c8aaf Binary files /dev/null and b/docs/python/images/flask-tutorial/debug-program-paused.png differ diff --git a/docs/python/images/flask-tutorial/debug-run-result.png b/docs/python/images/flask-tutorial/debug-run-result.png new file mode 100644 index 0000000000000000000000000000000000000000..e838bad04d16754c9bf7a4062a2470d478ee9a42 Binary files /dev/null and b/docs/python/images/flask-tutorial/debug-run-result.png differ diff --git a/docs/python/images/flask-tutorial/debug-select-configuration.png b/docs/python/images/flask-tutorial/debug-select-configuration.png new file mode 100644 index 0000000000000000000000000000000000000000..841cec4bbba95c3765231b7c612eb912cd14ad4e Binary files /dev/null and b/docs/python/images/flask-tutorial/debug-select-configuration.png differ diff --git a/docs/python/images/flask-tutorial/debug-status-bar.png b/docs/python/images/flask-tutorial/debug-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..3f4d860e2afe61ec3368bd2756e8f53c27358265 Binary files /dev/null and b/docs/python/images/flask-tutorial/debug-status-bar.png differ diff --git a/docs/python/images/flask-tutorial/debug-toolbar.png b/docs/python/images/flask-tutorial/debug-toolbar.png new file mode 100644 index 0000000000000000000000000000000000000000..e081dd4aec1d3be72c963ff63530b73242a1e0da Binary files /dev/null and b/docs/python/images/flask-tutorial/debug-toolbar.png differ diff --git a/docs/python/images/flask-tutorial/full-app.png b/docs/python/images/flask-tutorial/full-app.png new file mode 100644 index 0000000000000000000000000000000000000000..c5973fd08213843b61eeca1c1e6a1813eb4a72af Binary files /dev/null and b/docs/python/images/flask-tutorial/full-app.png differ diff --git a/docs/python/images/flask-tutorial/new-file-icon.png b/docs/python/images/flask-tutorial/new-file-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..ade4ecbcdeb1232c7f1ddefed7a6f3460cd84ca3 Binary files /dev/null and b/docs/python/images/flask-tutorial/new-file-icon.png differ diff --git a/docs/python/images/flask-tutorial/peek-definition.png b/docs/python/images/flask-tutorial/peek-definition.png new file mode 100644 index 0000000000000000000000000000000000000000..99bdc97c76c35aa38a1dc888e19bdb1fbb02531f Binary files /dev/null and b/docs/python/images/flask-tutorial/peek-definition.png differ diff --git a/docs/python/images/flask-tutorial/project-structure.png b/docs/python/images/flask-tutorial/project-structure.png new file mode 100644 index 0000000000000000000000000000000000000000..95805d774df821bf5897cbff80fea5308c476d2a Binary files /dev/null and b/docs/python/images/flask-tutorial/project-structure.png differ diff --git a/docs/python/images/flask-tutorial/reload-window-command.png b/docs/python/images/flask-tutorial/reload-window-command.png new file mode 100644 index 0000000000000000000000000000000000000000..53a649c2b6f649a1d6767217ff0cdc259cf29cc4 Binary files /dev/null and b/docs/python/images/flask-tutorial/reload-window-command.png differ diff --git a/docs/python/images/jupyter/code-cells-01.png b/docs/python/images/jupyter/code-cells-01.png new file mode 100644 index 0000000000000000000000000000000000000000..288ea9a9bf9a70e2728e529c6ed85af78bf95857 Binary files /dev/null and b/docs/python/images/jupyter/code-cells-01.png differ diff --git a/docs/python/images/jupyter/code-cells-02.png b/docs/python/images/jupyter/code-cells-02.png new file mode 100644 index 0000000000000000000000000000000000000000..e970417c96cb5be9bc7a9efb9593dfcddfbd08fa Binary files /dev/null and b/docs/python/images/jupyter/code-cells-02.png differ diff --git a/docs/python/images/jupyter/enter-url-auth-token.png b/docs/python/images/jupyter/enter-url-auth-token.png new file mode 100644 index 0000000000000000000000000000000000000000..e50d2f24e9b7fb8871ac05318cf44c2ba7d2dedf Binary files /dev/null and b/docs/python/images/jupyter/enter-url-auth-token.png differ diff --git a/docs/python/images/jupyter/jupyter-notebook.png b/docs/python/images/jupyter/jupyter-notebook.png new file mode 100644 index 0000000000000000000000000000000000000000..92376b3490161205d1bf6c956daee42979c36891 --- /dev/null +++ b/docs/python/images/jupyter/jupyter-notebook.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a8bc3fec17b582d2de5c65b8833e0051beb618fadb7371f1e93de6f80f496a9d +size 363848 diff --git a/docs/python/images/jupyter/jupyter-prompt.png b/docs/python/images/jupyter/jupyter-prompt.png new file mode 100644 index 0000000000000000000000000000000000000000..86a3a6e20652a0f55cca0bf08ac6a30e86ebe82d Binary files /dev/null and b/docs/python/images/jupyter/jupyter-prompt.png differ diff --git a/docs/python/images/jupyter/jupyter-running-remotely.png b/docs/python/images/jupyter/jupyter-running-remotely.png new file mode 100644 index 0000000000000000000000000000000000000000..82a071917f26feb1e26f951dd882fef157712d2c Binary files /dev/null and b/docs/python/images/jupyter/jupyter-running-remotely.png differ diff --git a/docs/python/images/linting/install-linter-message.png b/docs/python/images/linting/install-linter-message.png new file mode 100644 index 0000000000000000000000000000000000000000..8ab49da3e690146a4e03595e39fd29d410add15d Binary files /dev/null and b/docs/python/images/linting/install-linter-message.png differ diff --git a/docs/python/images/linting/lint-messages.png b/docs/python/images/linting/lint-messages.png new file mode 100644 index 0000000000000000000000000000000000000000..7a98b4c0153e11afe6213921c5b3d9b21935bf0a Binary files /dev/null and b/docs/python/images/linting/lint-messages.png differ diff --git a/docs/python/images/linting/linting.png b/docs/python/images/linting/linting.png new file mode 100644 index 0000000000000000000000000000000000000000..317bd91ba0bbb2552e25271ae56daf303ce282cf Binary files /dev/null and b/docs/python/images/linting/linting.png differ diff --git a/docs/python/images/shared/command-palette.png b/docs/python/images/shared/command-palette.png new file mode 100644 index 0000000000000000000000000000000000000000..2e53702c47365aae4c0278b526c94b960ba47264 Binary files /dev/null and b/docs/python/images/shared/command-palette.png differ diff --git a/docs/python/images/shared/debug-panel-initial-view.png b/docs/python/images/shared/debug-panel-initial-view.png new file mode 100644 index 0000000000000000000000000000000000000000..3065f8442d05c1d9ece0b43f6738896f222fe6c7 Binary files /dev/null and b/docs/python/images/shared/debug-panel-initial-view.png differ diff --git a/docs/python/images/shared/debug-toolbar.png b/docs/python/images/shared/debug-toolbar.png new file mode 100644 index 0000000000000000000000000000000000000000..e081dd4aec1d3be72c963ff63530b73242a1e0da Binary files /dev/null and b/docs/python/images/shared/debug-toolbar.png differ diff --git a/docs/python/images/shared/environment-in-status-bar.png b/docs/python/images/shared/environment-in-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..5823af993596be83f6a47a4313af229453253d9c Binary files /dev/null and b/docs/python/images/shared/environment-in-status-bar.png differ diff --git a/docs/python/images/shared/select-virtual-environment.png b/docs/python/images/shared/select-virtual-environment.png new file mode 100644 index 0000000000000000000000000000000000000000..4f24934ed7872155c71c0ccbbeee1fe804e876b6 Binary files /dev/null and b/docs/python/images/shared/select-virtual-environment.png differ diff --git a/docs/python/images/tutorial/breakpoint-set.png b/docs/python/images/tutorial/breakpoint-set.png new file mode 100644 index 0000000000000000000000000000000000000000..2598c3977b49a1661d62a60e0d4682bc32b15a3e Binary files /dev/null and b/docs/python/images/tutorial/breakpoint-set.png differ diff --git a/docs/python/images/tutorial/debug-configurations.png b/docs/python/images/tutorial/debug-configurations.png new file mode 100644 index 0000000000000000000000000000000000000000..2ad710f861000a58e17697676e07cc7379e39806 Binary files /dev/null and b/docs/python/images/tutorial/debug-configurations.png differ diff --git a/docs/python/images/tutorial/debug-external-terminal.png b/docs/python/images/tutorial/debug-external-terminal.png new file mode 100644 index 0000000000000000000000000000000000000000..be4105c52de2bfb8f437ac9d77075c58ba2fabb9 Binary files /dev/null and b/docs/python/images/tutorial/debug-external-terminal.png differ diff --git a/docs/python/images/tutorial/debug-icon.png b/docs/python/images/tutorial/debug-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..60c1745fd186f7a62a0825883c03afbd51b5c8f9 Binary files /dev/null and b/docs/python/images/tutorial/debug-icon.png differ diff --git a/docs/python/images/tutorial/debug-settings.png b/docs/python/images/tutorial/debug-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..6cd8c5ed3280cd650b762530400bdf36e0a0dcf6 Binary files /dev/null and b/docs/python/images/tutorial/debug-settings.png differ diff --git a/docs/python/images/tutorial/debug-step-01.png b/docs/python/images/tutorial/debug-step-01.png new file mode 100644 index 0000000000000000000000000000000000000000..7e03a836b398eddde23515a8e58be690cd10e5b4 Binary files /dev/null and b/docs/python/images/tutorial/debug-step-01.png differ diff --git a/docs/python/images/tutorial/debug-step-02.png b/docs/python/images/tutorial/debug-step-02.png new file mode 100644 index 0000000000000000000000000000000000000000..5c35f6b1bb610956c99a3d2093a7e47d89738d0e Binary files /dev/null and b/docs/python/images/tutorial/debug-step-02.png differ diff --git a/docs/python/images/tutorial/debug-step-03.png b/docs/python/images/tutorial/debug-step-03.png new file mode 100644 index 0000000000000000000000000000000000000000..9c913f3176761d15837925f8f8ff7104cfe28980 Binary files /dev/null and b/docs/python/images/tutorial/debug-step-03.png differ diff --git a/docs/python/images/tutorial/debug-toolbar.png b/docs/python/images/tutorial/debug-toolbar.png new file mode 100644 index 0000000000000000000000000000000000000000..e6e87259f862c5d4b88f7eaeae07188c5b910fa0 Binary files /dev/null and b/docs/python/images/tutorial/debug-toolbar.png differ diff --git a/docs/python/images/tutorial/hello-py-file-created.png b/docs/python/images/tutorial/hello-py-file-created.png new file mode 100644 index 0000000000000000000000000000000000000000..ec8291c864893b388f76467c013848e46b3f73c1 Binary files /dev/null and b/docs/python/images/tutorial/hello-py-file-created.png differ diff --git a/docs/python/images/tutorial/integrated-terminal.png b/docs/python/images/tutorial/integrated-terminal.png new file mode 100644 index 0000000000000000000000000000000000000000..b637c0192c594729c1104a0dec1622d049d252c8 Binary files /dev/null and b/docs/python/images/tutorial/integrated-terminal.png differ diff --git a/docs/python/images/tutorial/intellisense01.png b/docs/python/images/tutorial/intellisense01.png new file mode 100644 index 0000000000000000000000000000000000000000..f5dbdb39ea9955d4c8b3bde9e0fe900f8190c5d1 Binary files /dev/null and b/docs/python/images/tutorial/intellisense01.png differ diff --git a/docs/python/images/tutorial/intellisense02.png b/docs/python/images/tutorial/intellisense02.png new file mode 100644 index 0000000000000000000000000000000000000000..59a65c2aeb3c84525c2400e1a7c8d7d57e67fc03 Binary files /dev/null and b/docs/python/images/tutorial/intellisense02.png differ diff --git a/docs/python/images/tutorial/output-in-terminal.png b/docs/python/images/tutorial/output-in-terminal.png new file mode 100644 index 0000000000000000000000000000000000000000..36b1aa96fe0ad34fbcaf1a49a91e9c8b8d5b4021 Binary files /dev/null and b/docs/python/images/tutorial/output-in-terminal.png differ diff --git a/docs/python/images/tutorial/plot-output.png b/docs/python/images/tutorial/plot-output.png new file mode 100644 index 0000000000000000000000000000000000000000..f1f8c6d71a65ba6df7d42c044cbc3767f1c199c1 Binary files /dev/null and b/docs/python/images/tutorial/plot-output.png differ diff --git a/docs/python/images/tutorial/run-python-file-in-terminal.png b/docs/python/images/tutorial/run-python-file-in-terminal.png new file mode 100644 index 0000000000000000000000000000000000000000..ee90feaf195104db626259aadf6eed0a4b94d4f1 Binary files /dev/null and b/docs/python/images/tutorial/run-python-file-in-terminal.png differ diff --git a/docs/python/images/tutorial/social.png b/docs/python/images/tutorial/social.png new file mode 100644 index 0000000000000000000000000000000000000000..3df2ca0e7ab6c56ffcf6365cb88b9654315e9076 Binary files /dev/null and b/docs/python/images/tutorial/social.png differ diff --git a/docs/python/images/tutorial/toolbar-new-file.png b/docs/python/images/tutorial/toolbar-new-file.png new file mode 100644 index 0000000000000000000000000000000000000000..970d83dd6e2869c37ac75cd38f56ffe9e84e7423 Binary files /dev/null and b/docs/python/images/tutorial/toolbar-new-file.png differ diff --git a/docs/python/images/unit-testing/commands.png b/docs/python/images/unit-testing/commands.png new file mode 100644 index 0000000000000000000000000000000000000000..64e5868c657d8d048966c584c3256a5f548f36a3 Binary files /dev/null and b/docs/python/images/unit-testing/commands.png differ diff --git a/docs/python/images/unit-testing/discovery-failed-status-bar.png b/docs/python/images/unit-testing/discovery-failed-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..bc4ef59d2d419667a9b9256cdd48f36987084da1 Binary files /dev/null and b/docs/python/images/unit-testing/discovery-failed-status-bar.png differ diff --git a/docs/python/images/unit-testing/discovery-succeeded-status-bar.png b/docs/python/images/unit-testing/discovery-succeeded-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..673a7fc9b2694012c98cbe988dc8ee70c51efd58 Binary files /dev/null and b/docs/python/images/unit-testing/discovery-succeeded-status-bar.png differ diff --git a/docs/python/images/unit-testing/editor-adornments-pytest.png b/docs/python/images/unit-testing/editor-adornments-pytest.png new file mode 100644 index 0000000000000000000000000000000000000000..94c044510b8d1155e37f2c36644813078f7bd9eb Binary files /dev/null and b/docs/python/images/unit-testing/editor-adornments-pytest.png differ diff --git a/docs/python/images/unit-testing/editor-adornments-unittest.png b/docs/python/images/unit-testing/editor-adornments-unittest.png new file mode 100644 index 0000000000000000000000000000000000000000..839ec3f436bb627daa62d229c3fc68442e384997 Binary files /dev/null and b/docs/python/images/unit-testing/editor-adornments-unittest.png differ diff --git a/docs/python/images/unit-testing/install-framework.png b/docs/python/images/unit-testing/install-framework.png new file mode 100644 index 0000000000000000000000000000000000000000..e7c071deab3abeb0dc5d6094beec4388fc9423db Binary files /dev/null and b/docs/python/images/unit-testing/install-framework.png differ diff --git a/docs/python/images/unit-testing/python-test-log-output.png b/docs/python/images/unit-testing/python-test-log-output.png new file mode 100644 index 0000000000000000000000000000000000000000..c9bc1ec9b055074f56dc09d5f4e34bb9012779a3 Binary files /dev/null and b/docs/python/images/unit-testing/python-test-log-output.png differ diff --git a/docs/python/images/unit-testing/python-test-problems-output.png b/docs/python/images/unit-testing/python-test-problems-output.png new file mode 100644 index 0000000000000000000000000000000000000000..62514d480b4ff3d99cbc2bfc90c77aea8c574cc9 Binary files /dev/null and b/docs/python/images/unit-testing/python-test-problems-output.png differ diff --git a/docs/python/images/unit-testing/result-adornments-pytest.png b/docs/python/images/unit-testing/result-adornments-pytest.png new file mode 100644 index 0000000000000000000000000000000000000000..b1a47a8a5e666d99075f4cab3f8e60164fa597bf Binary files /dev/null and b/docs/python/images/unit-testing/result-adornments-pytest.png differ diff --git a/docs/python/images/unit-testing/result-adornments-unittest.png b/docs/python/images/unit-testing/result-adornments-unittest.png new file mode 100644 index 0000000000000000000000000000000000000000..079931ce940f1134bc1ffbced37d0ab265d33092 Binary files /dev/null and b/docs/python/images/unit-testing/result-adornments-unittest.png differ diff --git a/docs/python/images/unit-testing/run-test-commands.png b/docs/python/images/unit-testing/run-test-commands.png new file mode 100644 index 0000000000000000000000000000000000000000..28d284ff95688085ab0d0b600af9ca7801e5af79 Binary files /dev/null and b/docs/python/images/unit-testing/run-test-commands.png differ diff --git a/docs/python/images/unit-testing/test-explorer-run-all-tests.png b/docs/python/images/unit-testing/test-explorer-run-all-tests.png new file mode 100644 index 0000000000000000000000000000000000000000..f3620a6a133d085d7b38298d3ffaf39f9014f6d8 Binary files /dev/null and b/docs/python/images/unit-testing/test-explorer-run-all-tests.png differ diff --git a/docs/python/images/unit-testing/test-explorer-run-scoped-tests.png b/docs/python/images/unit-testing/test-explorer-run-scoped-tests.png new file mode 100644 index 0000000000000000000000000000000000000000..079e09ce516b18cce4849991341534d73ed6d7ee Binary files /dev/null and b/docs/python/images/unit-testing/test-explorer-run-scoped-tests.png differ diff --git a/docs/python/images/unit-testing/test-explorer.png b/docs/python/images/unit-testing/test-explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..6b01f57d2e6460e564cfe6a6639c9cbbcfa6d5f8 Binary files /dev/null and b/docs/python/images/unit-testing/test-explorer.png differ diff --git a/docs/python/images/unit-testing/test-results.png b/docs/python/images/unit-testing/test-results.png new file mode 100644 index 0000000000000000000000000000000000000000..1edec9dda268703fbea5e594d8740f39314eabab Binary files /dev/null and b/docs/python/images/unit-testing/test-results.png differ diff --git a/docs/python/jupyter-support.md b/docs/python/jupyter-support.md new file mode 100644 index 0000000000000000000000000000000000000000..500960a853dccdcf45ca849c9a9b4e2768483d4f --- /dev/null +++ b/docs/python/jupyter-support.md @@ -0,0 +1,103 @@ +--- +Order: 5 +Area: python +TOCTitle: Jupyter Support +ContentId: 779b7ad3-0aaa-4632-9998-0d8f964c0599 +PageTitle: Working with Jupyter Notebooks in Visual Studio Code +DateApproved: 01/30/2019 +MetaDescription: Working with Jupyter Notebooks in Visual Studio Code +MetaSocialImage: images/tutorial/social.png +--- + +# Working with Jupyter Notebooks in Visual Studio Code + +[Jupyter](http://jupyter-notebook.readthedocs.io/en/latest/) (formerly IPython) is an open-source project that lets you easily combine Markdown text and executable Python source code on one canvas called a *notebook*. + +To work with Jupyter notebooks, you must activate an Anaconda environment in VS Code, or another Python environment in which you've installed the [Jupyter package](https://pypi.org/project/jupyter/). To select an environment, use the **Python: Select Interpreter** command from the Command Palette (`kb(workbench.action.showCommands)`). + +Once the appropriate environment is activated, you can create and run Jupyter-like code cells, connect to a remote Jupyter server for running code cells, open a Jupyter notebook directly, and export Python files as Jupyter notebooks. + +## Jupyter code cells + +You define Jupyter-like code cells within Python code using a `#%%` comment: + +```python +#%% +msg = "Hello World" +print(msg) +``` + +When the Python extension detects a code cell, it adds a **Run Cell** or **Run All Cells** CodeLens above the comment: + +![Jupyter adornments for code cells in the VS Code editor](images/jupyter/code-cells-01.png) + +Selecting either command starts Jupyter (if necessary, which might take a minute), then runs the cell(s) in the Python interactive window. + +![Code cells running in a Python Interactive window](images/jupyter/code-cells-02.png) + +You can also run code cells using the **Python: Run Selection/Line in Python Terminal** command (`kbstyle(Shift+Enter)`). After using this command, the Python extension automatically moves the cursor to the next cell. If you're in the last cell in the file, the extension automatically inserts another `#%%` delimiter for a new cell, mimicking the behavior of a Jupyter notebook. + +### Python interactive window + +The Python interactive window, mentioned in the previous section, can be used as a standalone console with arbitrary code (with or without code cells). + +To use the window as a console, open it with the **Python: Show Python Interactive window** command from the Command Palette. You can then type in code, using `kbstyle(Enter)` to go to a new line and `kbstyle(Shift+Enter)` to run the code. + +To use the window with a file, use the **Run Current File in Python Interactive window** command from the Command Palette. + +## Connect to a remote Jupyter server + +You can offload intensive computation in a Jupyter notebook to other computers by connecting to a remote Jupyter server. Once connected, code cells run on the remote server rather than the local computer. + +To connect to a remote Jupyter server: + +1. Run the **Python: Specify Jupyter server URI** command from the Command Palette (`kb(workbench.action.showCommands)`). +2. When prompted, provide the server's URI (hostname) with the authentication token included with a `?token=` URL parameter. (If you start the server in the VS Code terminal with an authentication token enabled, the URL with the token typically appears in the terminal output from where you can copy it.) + + ![Prompt to supply a Jupyter server URI](images/jupyter/enter-url-auth-token.png) + +3. The Python interactive window indicates where code is run by displaying the URI (which is blurred out in the image below): + + ![The Python interactive window showing that code is running on a remote Jupyter server](images/jupyter/jupyter-running-remotely.png) + +## Open Jupyter notebooks + +When you've activated an environment with Jupyter installed, you can import a Jupyter notebook file (`.ipynb`) in VS Code as Python code. Once you've imported the file, you can run the code as you would with any other Python file and also use the VS Code debugger. Opening and debugging notebooks in VS Code is a convenient way to find and resolve code bugs, which is difficult to do directly in a Jupyter notebook. + +When you open a notebook file, the Python extension prompts you to import the notebook as a Python code file: + +![Prompt to import a Jupyter notebook file](images/jupyter/jupyter-prompt.png) + +Choose **Import**, wait a few seconds, and then VS Code opens the converted notebook in an untitled file. The notebook's cells are delimited in the Python file with `#%%` comments; Markdown cells are converted wholly to comments preceded with `#%% [markdown]`, and render as HTML in the interactive window alongside code and output such as graphs: + +![Jupyter notebook running in VS Code and the Python interactive window](images/jupyter/jupyter-notebook.png) + +If you open the file without importing, it appears as plain text. + +> **Note:** The first time you run code in a notebook file, the Python extension starts a Jupyter server. It may take some time for the server to start up and for the **Python Interactive** window to appear with the results of the code. + +## Debug a Jupyter notebook + +The Visual Studio Code debugger lets you step through your code, set breakpoints, examine state, and analyze problems. Using the debugger is a helpful way to find and correct issues in notebook code. + +1. In VS Code, activate a Python environment in which Jupyter is installed, as described at the beginning of this article. + +1. Import the notebook's `.ipynb` file into VS Code as described in the previous section. (Download the file first if you're using a cloud-based Jupyter environment such as [Azure Notebooks](https://docs.microsoft.com/azure/notebooks).) + +1. Follow the instructions to configure and run the debugger as described on [Tutorial - Configure and run the debugger](/docs/python/python-tutorial.md#configure-and-run-the-debugger), using your imported `.ipynb` file, of course, and setting a breakpoint in an appropriate location in your notebook code. + +1. To familiarize yourself with the general debugging features of VS Code, such as inspecting variables, setting breakpoints, and other activities, review [VS Code debugging](/docs/editor/debugging.md). + +1. As you find issues, stop the debugger, correct your code, save the file, and run the debugger again. + +1. When you're satisfied that all your code is correct. Save the file, then export the notebook as described in the following section. You can then upload the notebook to your normal Jupyter environment. + +## Export a Jupyter notebook + +In addition to opening a Jupyter notebook, you can also use one of the following commands from the Command Palette (`kb(workbench.action.showCommands)`) to export content from VS Code to a Jupyter notebook (with the `.ipynb` extension). + +- **Python: Export Current Python File as Jupyter Notebook**: creates a Jupyter notebook from the contents of the current file, using the `#%%` and `#%% [markdown]` delimiters to specify their respective cell types. +- **Python: Export Current Python File and Output as Jupyter Notebook**: creates a Jupyter notebook from the contents of the current file and includes output from code cells. +- **Python: Export Python Interactive window as Jupyter Notebook**: creates a Jupyter notebook from the contents of the Python interactive window. + +After exporting the contents, VS Code displays a prompt through which you can open the notebook in a browser. diff --git a/docs/python/linting.md b/docs/python/linting.md new file mode 100644 index 0000000000000000000000000000000000000000..dc2b1e4313727bc6265991137879f8137cd3a2b8 --- /dev/null +++ b/docs/python/linting.md @@ -0,0 +1,294 @@ +--- +Order: 3 +Area: python +TOCTitle: Linting +ContentId: 0ccb0e35-c4b2-4001-91bf-79ff1618f601 +PageTitle: Linting Python in Visual Studio Code +DateApproved: 10/10/2018 +MetaDescription: Linting Python in Visual Studio Code +MetaSocialImage: images/tutorial/social.png +--- +# Linting Python in Visual Studio Code + +Linting highlights syntactical and stylistic problems in your Python source code, which oftentimes helps you identify and correct subtle programming errors or unconventional coding practices that can lead to errors. For example, linting detects use of an uninitialized or undefined variable, calls to undefined functions, missing parentheses, and even more subtle issues such as attempting to redefine built-in types or functions. Linting is thus distinct from [Formatting](editing.md#formatting) because linting analyzes how the code runs and detects errors whereas formatting simply restructures how code *appears*. + +By default, linting for Python is enabled in Visual Studio Code using [Pylint](https://www.pylint.org), and you can enable other linters of your choice. You can easily enable and disable all linting by using the **Python: Enable Linting** command. + +## Enable linters + +To enable linters other than the default PyLint, open the Command Palette (`kb(workbench.action.showCommands)`) and select the **Python: Select Linter** command. This command adds `"python.lintingEnabled": true` to your settings, where `` is the name of the chosen linter. See [Specific linters](#specific-linters) for details. + +Enabling a linter prompts you to install the required packages in your selected environment for the chosen linter. + +![Prompt for installing a linter](images/linting/install-linter-message.png) + +> **Note**: If you're using a global environment and VS Code is not running elevated, linter installation may fail. In that case, either run VS Code elevated, or manually run the Python package manager to install the linter at an elevated command prompt for the same environment: for example `sudo pip3 install pylint` (macOS/Linux) or `pip install pylint` (Windows, at an elevated prompt) + +## Run linting + +To perform linting: + +- Linting runs automatically when you save a file. +- Open the Command Palette (`kb(workbench.action.showCommands)`), then enter and select **Python: Run Linting**. + +Issues are shown in the **Problems** panel and as underlines in the code editor. Hovering over an underlined issue displays the details: + +![Linting messages in the editor and the Problems panel](images/linting/lint-messages.png) + +## General linting settings + +The remainder of this article describes settings for linting in general as well as specific linters. You can add any of the settings to your user `settings.json` file (opened with the **File** > **Preferences** > **Settings** command `kb(workbench.action.openSettings)`). Refer to [User and Workspace settings](/docs/getstarted/settings.md) to find out more about working with settings in VS Code generally. + +To change the linting behavior across all enabled linters, modify the following settings: + +| Feature | Setting
(python.linting.) | Default value | +| --- | --- | --- | +| Linting in general | enabled | `true` | +| Linting on file save | lintOnSave | `true` | +| Maximum number of linting messages | maxNumberOfProblems | `100` | +| Exclude file and folder patterns | ignorePatterns | `[".vscode/*.py", "**/site-packages/**/*.py"]` | + +You can easily change `python.linting.enabled` by using the **Python: Enable Linting** command. + +When enabling `lintOnSave`, you might also want to enable the generic `files.autoSave` option (see [Save / Auto Save](/docs/editor/codebasics.md#save-auto-save)). The combination provides frequent linting feedback in your code as you type. + +## Specific linters + +The following table provides a summary of available Python linters and their basic settings. Only Pylint is enabled by default. For descriptions of individual settings, see the [Linter settings reference](/docs/python/settings-reference.md#linter-settings). + +| Linter | Package name for `pip install` command | Default state | True/false enable setting
(python.linting.) | Arguments setting
(python.linting.) | Custom path setting
(python.linting.) | +| --- | --- | --- | --- | --- | --- | +| [Pylint](#pylint) (default) | [pylint](https://pypi.org/project/pylint/) | Enabled | pylintEnabled | pylintArgs | pylintPath | +| [Flake8](#flake8) | [flake8](https://pypi.org/project/flake8/) | Disabled | flake8Enabled | flake8Args | flake8Path | +| [mypy](#mypy) | [mypy](https://pypi.org/project/mypy/) | Disabled | mypyEnabled | mypyArgs | mypyPath | +| [pydocstyle](#pydocstyle) | [pydocstyle](https://pypi.org/project/pydocstyle/) | Disabled | pydocstyleEnabled | pydocstyleArgs | pydocstylePath | +| [Pep8 (pycodestyle)](#pep8-pycodestyle) | [pep8](https://pypi.org/project/pep8/) | Disabled | pep8Enabled | pep8Args | pep8Path | +| [prospector](#prospector) | [prospector](https://pypi.org/project/prospector/) | Disabled | prospectorEnabled | prospectorArgs | prospectorPath | +| pylama | [pylama](https://pypi.org/project/pylama/) | Disabled | pylamaEnabled | pylamaArgs | pylamaPath | +| bandit | [bandit](https://pypi.org/project/bandit/) | Disabled | banditEnabled | banditArgs | banditPath | + +To select a different linter, use the **Python: Select Linter** command. You can also edit your settings manually to enable multiple linters. Note, however, that using the **Select Linter** command overwrites those edits. + +Custom arguments are specified in the appropriate arguments setting for each linter. Each top-level element of an argument string that's separated by a space on the command line must be a separate item in the args list. For example: + +```json +"python.linting.pylintArgs": ["--reports", "12", "--disable-msg", "I0011"], +"python.linting.flake8Args": ["--ignore=E24,W504", "--verbose"] +"python.linting.pydocstyleArgs": ["--ignore=D400", "--ignore=D4"] +``` + +Note that if a top-level element is a single value, as delineated by quotation marks or braces, is still appears as a single item in the list even if the value itself contains spaces. + +A custom path is generally unnecessary as the Python extension resolves the path to the linter based on the Python interpreter being used (see [Environments](/docs/python/environments.md)). To use a different version of a linter, specify its path in the appropriate custom path setting. For example, if your selected interpreter is a virtual environment but you want to use a linter that's installed in a global environment, then set the appropriate path setting to point to the global environment's linter. + +The sections that follow provide additional details for those individual linters linked in the table. In general, custom rules must be specified in a separate file as required by the linter you're using. + +## Pylint + +Pylint messages fall into the categories in the following table with the indicated mapping to VS Code categories. You can change the setting to change the mapping. + +| Pylint category | Description | VS Code category mapping | Applicable setting
(python.linting.) | +| --- | --- | --- | --- | +| Convention (C) | Programming standard violation | Information (green underline) | pylintCategorySeverity.convention | +| Refactor (R) | Bad code smell | Hint (light bulbs) | pylintCategorySeverity.refactor | +| Warning (W) | pylintCategorySeverity.warning | Warning | Python-specific problems | +| Error (E) | pylintCategorySeverity.error | Error (red underline) | Likely code bugs | +| Fatal (F) | pylintCategorySeverity.fatal | Error | An error prevented further Pylint processing | + +### Default Pylint rules + +Python in Visual Studio code is configured by default to use a set of linting rules that are friendly to the largest number of Python developers: + +- Enable all Error (E) and Fatal (F) messages. +- Disable all Convention (C) and Refactor (R) messages. +- Disable all Warning (W) messages except the following: + - unreachable (W0101): Unreachable code + - duplicate-key (W0109): Duplicate key %r in dictionary + - unnecessary-semicolon (W0301): Unnecessary semicolon + - global-variable-not-assigned (W0602): Using global for %r but no assignment is done + - unused-variable (W0612): Unused variable %r + - binary-op-exception (W0711): Exception to catch is the result of a binary "%s" operation + - bad-format-string (W1302): Invalid format string + - anomalous-backslash-in-string (W1401): Anomalous backslash in string + - bad-open-mode (W1501): "%s" is not a valid mode for open + +These rules are applied through the following default arguments passed to Pylint: + +``` +--disable=all --enable=F,E,unreachable,duplicate-key,unnecessary-semicolon,global-variable-not-assigned,unused-variable,binary-op-exception,bad-format-string,anomalous-backslash-in-string,bad-open-mode +``` + +These arguments are passed whenever the `python.linting.pylintUseMinimalCheckers` is set to `true` (the default). If you specify a value in `pylintArgs` or use a Pylint configuration file (see the next section), then `pylintUseMinimalCheckers` is implicitly set to `false`. + +For the complete list of Pylint messages, see [readable-pylint-messages](https://github.com/janjur/readable-pylint-messages/blob/master/README.md) (GitHub). + +### Command-line arguments and configuration files + +See [Pylint command line arguments](https://pylint.readthedocs.io/en/latest/user_guide/run.html#command-line-options) for general switches. Command-line arguments can be used to load Pylint plugins, such as the plugin for Django: + +```json +"python.linting.pylintArgs": ["--load-plugins", "pylint_django"] +``` + +Options can also be specified in a `pylintrc` or `.pylintrc` options file in the workspace folder, as described on [Pylint command line arguments](https://pylint.readthedocs.io/en/latest/user_guide/run.html#command-line-options). + +To control which Pylint messages are shown, add the following contents to an options file: + +```ini +[MESSAGES CONTROL] + +# Enable the message, report, category or checker with the given id(s). You can +# either give multiple identifier separated by comma (,) or put this option +# multiple time. +#enable= + +# Disable the message, report, category or checker with the given id(s). You +# can either give multiple identifier separated by comma (,) or put this option +# multiple time (only on the command line, not in the configuration file where +# it should appear only once). +#disable= +``` + +You can easily generate an options file using Pylint itself: + +```bash +pylint --generate-rcfile > .pylintrc +``` + +The generated file contains sections for all the Pylint options, along with documentation in the comments. + +## pydocstyle + +### Command-line arguments and configuration files + +See [pycodestyle Command Line Interface](http://www.pydocstyle.org/en/2.1.1/usage.html#cli-usage) for general options. For example, to ignore error D400 (first line should end with a period), add the following line to your `settings.json` file: + +```json +"python.linting.pydocstyleArgs": ["--ignore=D400"] +``` + +A code prefix also instructs pydocstyle to ignore specific categories of errors. For example, to ignore all Docstring Content issues (D4XXX errors), add the following line to `settings.json`: + +```json +"python.linting.pydocstyleArgs": ["--ignore=D4"] +``` + +More details can be found in the [pydocstyle documentation](http://www.pydocstyle.org/en/2.1.1/usage.html#cli-usage). + +Options can also be read from a `[pydocstyle]` section of any of the following configuration files: + +- `setup.cfg` +- `tox.ini` +- `.pydocstyle` +- `.pydocstyle.ini` +- `.pydocstylerc` +- `.pydocstylerc.ini` + +For more information, see [Configuration Files](http://www.pydocstyle.org/en/2.1.1/usage.html#configuration-files). + +### Message category mapping + +The Python extension maps all pydocstyle errors to the Convention (C) category. + +## Pep8 (pycodestyle) + +### Command-line arguments and configuration files + +See [pycodestyle example usage and output](https://pep8.readthedocs.io/en/latest/intro.html#example-usage-and-output) for general switches. For example, to ignore error E303 (too many blank lines), add the following line to your `settings.json` file: + +```json +"python.linting.pep8Args": ["--ignore=E303"] +``` + +Pep8 options are read from the `[pep8]` section of a `tox.ini` or `setup.cfg` file located in any parent folder of the path(s) being processed. For details, see [pycodestyle configuration](https://pep8.readthedocs.io/en/latest/intro.html#configuration). + +### Message category mapping + +The Python extension maps pep8 message categories to VS Code categories through the following settings. If desired, change the setting to change the mapping. + +| Pep8 category | Applicable setting
(python.linting.) | VS Code category mapping | +| --- | --- | --- | +| W | pep8CategorySeverity.W | Warning | +| E | pep8CategorySeverity.E | Error | + +## Prospector + +### Command-line arguments and configuration files + +See [Prospector Command Line Usage](https://prospector.readthedocs.io/en/master/usage.html) for general options. For example, to set a strictness level of "very high," add the following line to your `settings.json` file: + +```json +"python.linting.prospectorArgs": ["-s", "veryhigh"] +``` + +It's common with Prospector to use [profiles](https://prospector.readthedocs.io/en/master/profiles.html) to configure how Prospector runs. By default, Prospector loads the profile from a `.prospector.yaml` file in the current folder. + +Because Prospector calls other tools, such as Pylint, any configuration files for those tools override tool-specific settings in `.prospector.yaml`. For example, suppose you specify the following in `.prospector.yaml`: + +```yaml +pylint: + disable: + - too-many-arguments +``` + +If you also have a `.pylintrc` file that enables the `too-many-arguments` warning, you continue to see the warning from Pylint within VS Code. + +### Message category mapping + +The Python extension maps all Prospector errors and warnings to the Error (E) category. + +## Flake8 + +### Command-line arguments and configuration files + +See [Invoking Flake8](http://flake8.pycqa.org/en/latest/user/invocation.html) for general switches. For example, to ignore error E303 (too many blank lines), use the following setting: + +```json +"python.linting.flake8Args": ["--ignore=E303"] +``` + +By default, Flake8 ignores E121, E123, E126, E226, E24, and E704. + +Flake8 user options are read from the `C:\Users\\.flake8` (Windows) or `~/.config/flake8` (macOS/Linux) file. + +At the project level, options are read from the `[flake8]` section of a `tox.ini`, `setup.cfg`, or `.flake8` file. + +For details, see [Flake8 configuration](http://flake8.pycqa.org/en/latest/user/configuration.html). + +### Message category mapping + +The Python extension maps flake8 message categories to VS Code categories through the following settings. If desired, change the setting to change the mapping. + +| Flake8 category | Applicable setting
(python.liting.) | VS Code category mapping | +| --- | --- | --- | +| F | flake8CategorySeverity.F | Error | +| E | flake8CategorySeverity.E | Error | +| W | flake8CategorySeverity.W | Warning | + +## mypy + +### Message category mapping + +The Python extension maps mypy message categories to VS Code categories through the following settings. If desired, change the setting to change the mapping. + +| mypy category | Applicable setting
(python.linting.) | VS Code category mapping | +| --- | --- | --- | +| error | mypyCategorySeverity.error | Error | +| note | mypyCategorySeverity.note | Information | + +## Troubleshooting linting + +| Error message | Cause | Solution | +| --- | --- | --- | +| ... unable to import \ | The Python extension is using the wrong version of Pylint. | Ensure that the `pythonPath` setting points to a valid Python installation where Pylint is installed. Alternately, set the `python.linting.pylintPath` to an appropriate version of Pylint for the Python interpreter being used. | +| Linting with \ failed ... | The path to the Python interpreter is incorrect. | Check the `pythonPath` setting (see [Environments](/docs/python/environments.md)). | +| | The linter has not been installed in the current Python environment. | Open a command window, navigate to the location of the Python interpreter in the `pythonPath` setting, and run `pip install` for the linter. | +| | The path to the linter is incorrect. | Ensure that the appropriate `python.linting.Path` setting for the linter is correct. | +| | Custom arguments are defined incorrectly. | Check the appropriate `python.linting.Args` settings, and that the value of the setting is a list of the argument elements that are separated by spaces. For example, `"python.linting.pylintPath": "pylint --load-plugins pylint_django"` is incorrect. The correct syntax is `"python.linting.pylintArgs": ["--load-plugins", "pylint_django"]`. | + +## Next steps + +- [Debugging](/docs/python/debugging.md) - Learn to debug Python both locally and remotely. +- [Unit testing](/docs/python/unit-testing.md) - Configure unit test environments and discover, run, and debug tests. +- [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +- [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. diff --git a/docs/python/python-tutorial.md b/docs/python/python-tutorial.md new file mode 100644 index 0000000000000000000000000000000000000000..defdff825dc315ca84239d9524245d00ac56a4b6 --- /dev/null +++ b/docs/python/python-tutorial.md @@ -0,0 +1,299 @@ +--- +Order: 1 +Area: python +TOCTitle: Tutorial +ContentId: 77828f36-ae45-4887-b25c-34545edd52d3 +PageTitle: Get Started Tutorial for Python in Visual Studio Code +DateApproved: 01/29/2019 +MetaDescription: A Python hello world tutorial using the Python extension in Visual Studio Code (a great Python IDE like PyCharm, if not the best Python IDE) +MetaSocialImage: images/tutorial/social.png +--- +# Getting Started with Python in VS Code + +In this tutorial, you use Python 3 to create the simplest Python "Hello World" application in Visual Studio Code. By using the Python extension, you make VS Code into a great lightweight Python IDE (which you may find a productive alternative to PyCharm). + +This tutorial is intended to introduce you to VS Code as a Python environment, primarily how to edit, run, and debug code. This tutorial is not intended to teach you Python itself. Once you are familiar with the basics of VS Code, you can then follow any of the [programming tutorials](https://wiki.python.org/moin/BeginnersGuide/Programmers) listed on python.org within the context of VS Code for an introduction to the language. + +If you have any problems, feel free to file an issue for this tutorial in the [VS Code documentation repository](https://github.com/Microsoft/vscode-docs/issues). + +> **Note**: You can use VS Code with Python 2 with this tutorial, but you need to make appropriate changes to the code, which are not covered here. + +## Prerequisites + +To successfully complete this tutorial, complete the following requirements: + +1. Install the [Python extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-python.python). For details on installing extensions, see [Extension marketplace](/docs/editor/extension-gallery.md). The Python extension is named **Python** and published by Microsoft. + +1. Install a version of Python 3 (for which this tutorial is written). Options include: + - (All operating systems) A download from [python.org](https://www.python.org/downloads/); you can typically use the **Download Python 3.7.1** button that appears first on the page (or whatever is the latest version). + - (Linux) The built-in Python 3 installation works well, but to install other Python packages you must install `pip` with [`get-pip.py`](https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py). + - (macOS) An installation through [Homebrew](https://brew.sh/) on macOS using `brew install python3` (the system install of Python on macOS is not supported). + - (All operating systems) A download from [Anaconda](https://www.anaconda.com/download/) (for data science purposes). + +1. On Windows, make sure the location of your Python interpreter (that is, the folder where it's installed, like `c:\python32`) is included in your PATH environment variable. You can check the location by running `path` at the command prompt. If the Python interpreter's folder isn't included, open Windows Settings, search for "environment", select **Edit environment variables for your account**, then edit the **Path** variable to include that folder. + +1. On MacOS, make sure the location of your VS Code installation is included in your PATH environment variable. See [the setup instructions](/docs/setup/mac.md#launching-from-the-command-line) for more information. + +## Start VS Code in a project (workspace) folder + +At a command prompt or terminal, create an empty folder called "hello", navigate into it, and open VS Code (`code`) in that folder (`.`) by entering the following commands: + +```bash +mkdir hello +cd hello +code . +``` + +By starting VS Code in a folder, that folder becomes your "workspace". VS Code stores settings that are specific to that workspace in `.vscode/settings.json`, which are separate from user settings that are stored globally. + +Alternately, you can run VS Code through the operating system UI, then use **File > Open Folder** to open the project folder. + +## Select a Python interpreter + +Python is an interpreted language, and in order to run Python code and get Python IntelliSense, you must tell VS Code which interpreter to use. + +From within VS Code, select a Python 3 interpreter by opening the **Command Palette** (`kb(workbench.action.showCommands)`), start typing the **Python: Select Interpreter** command to search, then select the command. You can also use the **Select Python Environment** option on the Status Bar if available (it may already show a selected interpreter, too): + +![No interpreter selected](images/environments/no-interpreter-selected-statusbar.png) + +The command presents a list of available interpreters that VS Code can find automatically, including virtual environments. If you don't see the desired interpreter, see [Configuring Python environments](/docs/python/environments.md). + +Selecting an interpreter sets the `python.pythonPath` value in your workspace settings to the path of the interpreter. To see the setting, select **File** > **Preferences** > **Settings** (**Code** > **Preferences** > **Settings** on macOS), then select the **Workspace Settings** tab. + +> **Note**: If you select an interpreter without a workspace folder open, VS Code sets `python.pythonPath` in your user settings instead, which sets the default interpreter for VS Code in general. The user setting makes sure you always have a default interpreter for Python projects. The workspace settings lets you override the user setting. + +## Create a Python Hello World source code file + +From the File Explorer toolbar, click the New File button on the `hello` folder: + +![File Explorer New File](images/tutorial/toolbar-new-file.png) + +Name the file `hello.py`, and it automatically opens in the editor: + +![File Explorer hello.py](images/tutorial/hello-py-file-created.png) + +By using the `.py` file extension, you tell VS Code to interpret this file as a Python program, so that it evaluates the contents with the Python extension and the selected interpreter. + +Next, start entering the following source code if using Python 3: + +```python +msg = "Hello World" +print(msg) +``` + +When you start typing `print`, notice how [IntelliSense](/docs/editor/intellisense.md) presents auto-completion options. + +![IntelliSense appearing for Python code](images/tutorial/intellisense01.png) + +IntelliSense and auto-completions work for standard Python modules as well as other packages you've installed into the environment of the selected Python interpreter. It also provides completions for methods available on object types. For example, because the `msg` variable contains a string, IntelliSense provides string methods when you type `msg.`: + +![IntelliSense appearing for a variable whose type provides methods](images/tutorial/intellisense02.png) + +Feel free to experiment with IntelliSense some more, but then revert your changes so you have only the `msg` variable and the `print` call, and save the file (`kb(workbench.action.files.save)`). + +For full details on editing, formatting, and refactoring, see [Editing code](/docs/python/editing.md). The Python extension also has full support for [Linting](/docs/python/linting.md). + +## Run Hello World + +It's simple to run `hello.py` with Python. Right-click in the editor and select **Run Python File in Terminal** (which saves the file automatically): + +![Run Python File in Terminal command in the Python editor](images/tutorial/run-python-file-in-terminal.png) + +The command opens a terminal panel in which your Python interpreter is automatically activated, then runs `python3 hello.py` (macOS/Linux) or `python hello.py` (Windows): + +![Program output in a Python terminal](images/tutorial/output-in-terminal.png) + +There are two other ways you can run Python within VS Code: + +- Select one or more lines, then press `kbstyle(Shift+Enter)` or right-click and select **Run Selection/Line in Python Terminal**. This command is convenient for testing just a part of a file. +- Use the **Python: Start REPL** command to open a REPL terminal for the currently selected Python interpreter. In the REPL, you can then enter and run lines of code one at a time. + +## Configure and run the debugger + +Let's now try debugging our simple Hello World program. + +First, set a breakpoint on line 2 of `hello.py` by placing the cursor on the `print` call and pressing `kb(editor.debug.action.toggleBreakpoint)`. Alternately, just click in the editor's left gutter, next to the line numbers. When you set a breakpoint, a red circle appears in the gutter. + +![Setting a breakpoint in hello.py](images/tutorial/breakpoint-set.png) + +Next, select the Debug View in the sidebar: + +![Debug icon](images/tutorial/debug-icon.png) + +Then select the settings icon on the debug toolbar (or use the **Debug** > **Open configurations** menu command): + +![Debug toolbar settings command](images/tutorial/debug-settings.png) + +After a few moments, the command creates a `launch.json` file that contains a number of configurations, which appear in the configurations drop-down: + +![Debug configurations after launch.json is created](images/tutorial/debug-configurations.png) + +**Note**: VS Code uses JSON files for all of its various configurations; `launch.json` is the standard name for a file containing debugging configurations. + +These different configurations are fully explained in [Debugging configurations](/docs/python/debugging.md); for now, just select **Python: Current File (Integrated Terminal)**, which is the configuration that runs the current file shown in the editor using the currently selected Python interpreter. + +>> **WARNING**: Due to a [current bug in the debugger](https://github.com/Microsoft/vscode-python/issues/4223), the following discussion of the `stopOnEntry` setting doesn't work and causes the debugger to fail to start. Instead, set a breakpoint on the first line and do **not** add `stopOnEntry` to the configuration. +> +> Affected paragraphs: +> +> To automatically stop the debugger on the first line when the program starts, add a `"stopOnEntry": true` setting to the "Python: Current File" configuration in `launch.json`, so that the whole configuration appears as follows: +> +> ```json +> { +> "name": "Python: Current File (Integrated Terminal)", +> "type": "python", +> "request": "launch", +> "program": "${file}", +> "console": "integratedTerminal", +> "stopOnEntry": true +> }, +> ``` +> +> Save `launch.json` after making changes. + +> **Tip:** If you need to specify the exact folder containing the interpreter to use for debugging, include an entry for `pythonPath` in the configuration, such as `"pythonPath": "${workspaceFolder}"` or `"pythonPath": "${workspaceFolder}/.venv"`. + +Switch to `hello.py` in the editor, then run the debugger by selecting the arrow in the Debug toolbar or pressing `kb(workbench.action.debug.start)`. The debugger stops at the first line of the file breakpoint (or the first line if `stopOnEntry` is set to true). The current line is indicated with a yellow arrow in the left margin. If you're stopped on the first line and examine the **Local** variables window at this point, you see that only automatic dunder variables are defined: + +![Debugging step 1 - stop on entry](images/tutorial/debug-step-01.png) + +A debug toolbar appears along the top with the following commands from left to right: continue (`kb(workbench.action.debug.start)`), step over (`kb(workbench.action.debug.stepOver)`), step into (`kb(workbench.action.debug.stepInto)`), step out (`kb(workbench.action.debug.stepOut)`), restart (`kb(workbench.action.debug.restart)`), and stop (`kb(workbench.action.debug.stop)`). + +![Debugging toolbar](images/tutorial/debug-toolbar.png) + +The Status Bar also changes color (orange in many themes) to indicate that you're in debug mode. The **Python Debug Console** also appears automatically in the lower right panel to show the commands being run, along with the program output. + +To continue running the program, select the continue command on the debug toolbar (`kb(workbench.action.debug.start)`). The debugger runs the program to the next breakpoint. The now-defined `msg` variable appears in the **Local** pane + +![Debugging step 2 - variable defined](images/tutorial/debug-step-02.png) + +You can also work with variables in the **Debug Console** (If you don't see it, select **Debug Console** in the lower right area of VS Code, or select it from the **...** menu.) Then try entering the following lines, one by one, at the **>** prompt at the bottom of the console: + +```python +msg +msg.capitalize() +msg.split() +``` + +![Debugging step 3 - using the debug console](images/tutorial/debug-step-03.png) + +Select the green arrow again to run the program to completion. "Hello World" appears in the **Python Debug Console** if you switch back to it, and VS Code exits debugging mode once the program is complete. + +If you restart the debugger, the debugger again stops on the first breakpoint, (or the first line is `stopOnEntry` is set to true, in which case the debugger stops before any code is run.) + +To stop running a program before it's complete, use the red square stop button on the debug toolbar (`kb(workbench.action.debug.stop)`), or use the **Debug > Stop debugging** menu command. + +For full details, see [Debugging configurations](/docs/python/debugging.md), which includes notes on how to use a specific Python interpreter for debugging. + +> **Tip: Use Logpoints instead of print statements**: Developers often litter source code with `print` statements to quickly inspect variables without necessarily stepping through each line of code in a debugger. In VS Code, you can instead use **Logpoints**. A Logpoint is like a breakpoint except that it logs a message to the console and doesn't stop the program. For more information, see [Logpoints](/docs/editor/debugging.md#logpoints) in the main VS Code debugging article. + +### Troubleshooting + +If for some reason VS Code doesn't generate `launch.json` for you, create the `.vscode/launch.json` file within the project folder (creating the `.vscode` folder if you need to), then paste the following contents into `launch.json`: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Python: Current File (Integrated Terminal)", + "type": "python", + "request": "launch", + "program": "${file}", + "console": "integratedTerminal" + } + ] +} +``` + +If you see "SyntaxError: invalid syntax" as shown below, you may have attempted to start debugging when `launch.json` was showing in the editor. The error occurs because `launch.json` is not Python code like `hello.py`: + +```bash + // Use IntelliSense to learn about possible attributes. + ^ +SyntaxError: invalid syntax +``` + +Select `hello.py` and try again. Alternately, create a debug configuration specifically for the `hello.py` file by adding the following lines in `launch.json` within the `configuration` array. Then select this configuration in the debugger drop-down and start the debugger again. + +```json + { + "name": "Python: hello.py", + "type": "python", + "request": "launch", + "program": "${workspaceFolder}/hello.py", + "console": "integratedTerminal" + }, +``` + +If you see the message, "Python interpreter is not found because python.exe is not in the workspace directory," or "You need to install a Python interpreter before you start debugging," then you may have `pythonPath: ${workspaceFolder}` in your `launch.json` file, but your Python interpreter actually exists in a different path. Check the value, or remove the `pythonPath` property altogether. + +## Install and use packages + +Let's now run an example that's a little more interesting. In Python, packages are how you obtain any number of useful code libraries, typically from [PyPI](https://pypi.org/). For this example, you use the `matplotlib` and `numpy` packages to create a graphical plot as is commonly done with data science. (Note that `matplotlib` cannot show graphs when running in the [Windows Subsystem for Linux](https://docs.microsoft.com/windows/wsl/about) as it lacks the necessary UI support.) + +Return to the **Explorer** view (the top-most icon on the left side, which shows files), create a new file called `standardplot.py`, and paste in the following source code: + +```python +import matplotlib.pyplot as plt +import numpy as np + +x = np.linspace(0, 20, 100) # Create a list of evenly-spaced numbers over the range +plt.plot(x, np.sin(x)) # Plot the sine of each x point +plt.show() # Display the plot +``` + +> **Tip**: If you enter the above code by hand, you may find that auto-completions change the names after the `as` keywords when you press `kbstyle(Enter)` at the end of a line. To avoid this, type a space, then `kbstyle(Enter)`. + +Next, try running the file in the debugger using the "Python: Current file" configuration as described in the last section. (If you still have `"stopOnEntry": true` in that configuration, you need to select the run command again to continue.) + +Unless you're using an Anaconda distribution or have previously installed the `matplotlib` package, you should see the message, "ModuleNotFoundError: No module named 'matplotlib'". Such a message indicates that the required package isn't available in your system. + +To install the `matplotlib` package (which also installs `numpy` as a dependency), stop the debugger and use the Command Palette to run **Terminal: Create New Integrated Terminal** (`kb(workbench.action.terminal.new)`)). This command opens a command prompt for your selected interpreter. Then enter the following commands as appropriate for your operating system: + +> **Note**: The commands may require elevation if the Python interpreter is installed in a protected area of the file system; if you don't have admin privileges on the computer you're using, you may not be allowed to install the package. In that case, you need to use a *virtual environment* instead (see [Environments](/docs/python/environments.md#global-virtual-and-conda-environments)). If you are unable to install the package or encounter other problems, please [file an issue on GitHub](https://github.com/Microsoft/vscode-docs/issues) so we can help you investigate. + +```bash +# Don't use with Anaconda distributions because they include matplotlib already. + +# macOS +sudo python3 -m pip install matplotlib + +# Windows (may require elevation) +python -m pip install matplotlib + +# Linux (Debian) +sudo apt-get install python3-tk +python3 -m pip install matplotlib +``` + +Rerun the program now (with or without the debugger) and after a few moments a plot window appears with the output: + +![matplotlib output](images/tutorial/plot-output.png) + +### Use a virtual environment + +A best practice among Python developers is to avoid installing packages into a global interpreter environment, as we did in the previous section. You instead use a project-specific *virtual environment* that contains a copy of a global interpreter. Once you activate that environment, any packages you then install are isolated from other environments. Such isolation reduces many complications that can arise from conflicting package versions. + +For examples of creating and activating a virtual environment and installing packages, see the [Django tutorial](/docs/python/tutorial-django.md) and the [Flask tutorial](/docs/python/tutorial-flask.md). + +## Next steps + +You can configure VS Code to use any Python environment you have installed, including virtual and conda environments. You can also use a separate environment for debugging. For full details, see [Environments](/docs/python/environments.md). + +To learn more about the Python language, follow any of the [programming tutorials](https://wiki.python.org/moin/BeginnersGuide/Programmers) listed on python.org within the context of VS Code. + +To learn to build web apps with the Django and Flask frameworks, see the following tutorials: + +- [Use Django in Visual Studio Code](/docs/python/tutorial-django.md) +- [Use Flask in Visual Studio Code](/docs/python/tutorial-flask.md) + +There is then much more to explore with Python in Visual Studio Code: + +- [Editing code](/docs/python/editing.md) - Learn about autocomplete, IntelliSense, formatting, and refactoring for Python. +- [Linting](/docs/python/linting.md) - Enable, configure, and apply a variety of Python linters. +- [Debugging](/docs/python/debugging.md) - Learn to debug Python both locally and remotely. +- [Unit testing](/docs/python/unit-testing.md) - Configure unit test environments and discover, run, and debug tests. +- [Settings reference](/docs/python/settings-reference.md) - Explore the full range of Python-related settings in VS Code. +- [Deploy Python to Azure App Service using containers](/docs/python/tutorial-deploy-containers.md) +- [Deploy Python to Azure App Service on Linux (Preview)](/docs/python/tutorial-deploy-app-service-on-linux.md) diff --git a/docs/python/settings-reference.md b/docs/python/settings-reference.md new file mode 100644 index 0000000000000000000000000000000000000000..92acd5d6704753d60786c924e65e64bcd3e79865 --- /dev/null +++ b/docs/python/settings-reference.md @@ -0,0 +1,221 @@ +--- +Order: 12 +Area: python +TOCTitle: Settings Reference +ContentId: d256dc5c-95e9-4c02-a82f-947bf34a3517 +PageTitle: Settings Reference for Python +DateApproved: 09/03/2018 +MetaDescription: Settings Reference for the Python extension in Visual Studio Code +MetaSocialImage: images/tutorial/social.png +--- +# Python settings reference + +The Python Extension for Visual Studio Code is highly configurable. This page describes the key settings you can work with. + +Refer to [User and workspace settings](/docs/getstarted/settings.md) to find our more about working with settings in VS Code generally. + +## General settings + +| Setting | Default | Description | +| --- | --- | --- | +| python.condaPath | `"conda"` | Path to the `conda` executable. | +| python.pythonPath | `"python"` | Path to the python interpreter, or the path to a folder containing the Python interpreter. Can use variables like `${workspaceFolder}` and `${workspaceFolder}/.venv`. Using a path to a folder allows anyone working with a project to create an environment in the `.venv` folder as appropriate to their operating system, rather than having to specify an exact platform-dependent path. The `settings.json` file can then be included in a source code repository. | +| python.pipenvPath | `"pipenv"` | Path to the pipenv executable to use for activation. | +| python.disableInstallationCheck | `false` | If set to `true`, disables a warning from the extension if no Python interpreter is installed. On macOS, also disables a warning that appears if you're using the OS-installed Python interpreter. It's generally recommended to install a separate interpreter on macOS. | +| python.venvPath | `""` | Path to a folder, where virtual environments are created. Depending on the virtualization tool used, it can be the project itself: `${workspaceFolder}`, or separate folder for all virtual environments located side by side: `.\envs`, `~/.virtualenvs`, and so on. | +| python.envFile | `"${workspaceFolder}/.env"` | Absolute path to a file containing environment variable definitions. See [Configuring Python environments - environment variable definitions file](/docs/python/environments.md#environment-variable-definitions-file). | +| python.globalModuleInstallation | `false` | Specifies whether to install packages for the current user only using the `--user` command-line argument (the default), or to install for all users in the global environment (when set to `true`). Ignored when using a virtual environment. For more information on the `--user`argument, see [pip - User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs). | +| python.terminal.launchArgs | `[]` | Launch arguments that are given to the Python interpreter when you run a file using commands such as **Python: Run Python File in Terminal**. In the `launchArgs` list, each item is a top-level command-line element that's separated by a space (quoted values that contain spaces are a single top-level element and are thus one item in the list). For example, for the arguments `--a --b --c {"value1" : 1, "value2" : 2}`, the list items should be `["--a", "--b", "--c", "{\"value1\" : 1, \"value2\" : 2}\""]`. Note that Visual Studio code ignores this setting when debugging because it instead uses arguments from your selected debugging configuration in `launch.json`. | +| python.terminal.executeInFileDir | `false` | Indicates whether to run a file in the file's directory instead of the current folder. | +| python.terminal.activateEnvironment | `true` | Indicates whether to automatically activate the environment you select using the **Python: Select Interpreter** command. For example, when this setting is `true` and you select a virtual environment, the extension automatically runs the environment's *activate* command (`source env/bin/activate` on macOS/Linux; `env\scripts\activate` on Windows). | + +## Workspace symbol (tags) settings + +Workspace symbols are symbols in C source code generated by the ctags tool (described on [Wikipedia](https://en.wikipedia.org/wiki/Ctags) and on [ctags.sourceforge.net](http://ctags.sourceforge.net/ctags.html)). To quote Wikipedia, ctags "generates an index (or tag) file of names found in source and header files of various programming languages." Where Python is concerned, ctags makes it easier to jump to defined functions and other symbols in C/C++ extension modules. + +| Setting
(python.workspaceSymbols.) | Default | Description | +| --- | --- | --- | +| tagFilePath | `"${workspaceFolder}/.vscode/tags"` | Fully qualified path to tag file (an exuberant ctag file), used to provide workspace symbols. | +| enabled | `true` | Specifies whether to enable the Workspace Symbol provider. | +| rebuildOnStart | `true` | Specifies whether to rebuild the tags file on start. | +| rebuildOnFileSave | `true` | Specifies whether to rebuild the tags file on when saving a Python file. | +| ctagsPath | `"ctags"` | Fully qualified path to the ctags executable; default value assumes it's in the current environment. | +| exclusionPatterns | `["**/site-packages/**"]` | Pattern used to exclude files and folders from ctags. | + +## Code analysis settings + +### IntelliSense engine settings + +| Setting | Default | Description | +| --- | --- | --- | +| python.jediEnabled | `true` | Indicates whether to use Jedi as the IntelliSense engine (true) or the [Microsoft Python Language Server](https://devblogs.microsoft.com/python/introducing-the-python-language-server) (false). Note that the language server requires a platform that [supports .NET Core 2.1 or newer](https://docs.microsoft.com/dotnet/core/rid-catalog). | +| python.jediPath | `""` | Path to folder containing the Jedi library (folder should contain a `jedi` subfolder). | +| python.jediMemoryLimit | 0 | Memory limit for the Jedi completion engine in megabytes. Zero (the default) means 1024 MB. -1 disables the memory limit check. | + +### Python Language Server settings + +The language server settings apply when `python.jediEnabled` is `false`. + +| Setting
(python.analysis.) | Default | Description | +| --- | --- | --- | +| diagnosticPublishDelay | `1000` | The number of milliseconds to wait before transferring diagnostic messages to the problems list. | +| disabled
errors
warnings
information | `[]` | List of diagnostics messages to suppress or show as errors, warnings, or information. See below for applicable values. The classification of messages affects both what's shown in the Problems window and in the editor (such as the color of the underlining). | +| logLevel | `"Error"` | Defines the types of log messages that language server writes into the Problems window, one of "Error", "Warning", "Information", and "Trace". The "Warning" level implicitly includes "Error"; "Information" implicitly includes "Warning" and "Error"; "Trace" includes all messages. | +| openFilesOnly | `true` | When true, shows only errors and warnings for open files rather than for the entire workspace. | +| symbolsHierarchyDepthLimit | `10` | Limits the depth of the symbol tree in the document outline. | +| typeshedPaths | `[]` | Paths to look for [typeshed modules](https://github.com/python/typeshed/) (github.com). | + +The `disabled`, `errors`, `warnings`, and `information` settings can contain the following values: + +| Value | Default type | Message text | +| --- | --- | --- | +| "not-callable" | Warning | (object may not be callable) | +| "used-before-assignment" | Warning | (unknown variable '{0}') | +| "unresolved-import" | Warning | "Unable to resolve 'module_name'. IntelliSense may be missing for this module." | + +To suppress the "used-before-assignment" messages, for example, use the setting `"python.analysis.disabled": ["used-before-assignment"]`. + +## AutoComplete settings + +| Setting
(python.autoComplete.) | Default | Description | See also | +| --- | --- | --- | --- | +| addBrackets | `false` | Specifies whether VS Code automatically adds parentheses (`()`) when autocompleting a function name. | [Editing](/docs/python/editing.md#autocomplete-and-intellisense) | +| preloadModules | `[]` | Specifies modules to pre-load to improve autocomplete performance. | [Editing](/docs/python/editing.md#autocomplete-and-intellisense) | +| extraPaths | `[]` | Specifies locations of additional packages for which to load autocomplete data. | [Editing](/docs/python/editing.md#autocomplete-and-intellisense) | + +## Formatting settings + +| Setting
(python.formatting.) | Default | Description | See also | +| --- | --- | --- | --- | +| provider | `"autopep8"` | Specifies the formatter to use, either "autopep8", "black", or "yapf". |[Editing - Formatting](/docs/python/editing.md#formatting) | +| autopep8Path | `"autopep8"` | Path to autopep8 | [Editing - Formatting](/docs/python/editing.md#formatting) | +| autopep8Args| `[]` | Arguments for autopep8, where each top-level element that's separated by a space is a separate item in the list. | [Editing - Formatting](/docs/python/editing.md#formatting) | +| blackPath | `"black"` | Path to black | [Editing - Formatting](/docs/python/editing.md#formatting) | +| blackArgs| `[]` | Arguments for black, where each top-level element that's separated by a space is a separate item in the list. | [Editing - Formatting](/docs/python/editing.md#formatting) | +| yapfPath | `"yapf"` | Path to yapf | [Editing - Formatting](/docs/python/editing.md#formatting) | +| yapfArgs| `[]` | Arguments for yapf, where each top-level element that's separated by a space is a separate item in the list. | [Editing - Formatting](/docs/python/editing.md#formatting) | + +## Refactoring - Sort Imports settings + +| Setting
(python.sortImports.) | Default | Description | See also | +| --- | --- | --- | --- | +| path | `""` | Path to isort script | [Editing - Refactoring - Sort Imports](/docs/python/editing.md#sort-imports) | +| args | `[]` | Arguments for isort, each argument as a separate item in the array. | [Editing - Refactoring - Sort Imports](/docs/python/editing.md#sort-imports) | + +## Linting settings + +### General + +| Setting
(python.linting.) | Default | Description | See also | +| --- | --- | --- | --- | +| enabled | `true` | Specifies whether to enable linting in general. | [Linting](/docs/python/linting.md) | +| lintOnSave | `true` | Specifies whether to line when saving a file. | [Linting](/docs/python/linting.md) | +| maxNumberOfProblems | `100` | Limits the number of linting messages shown. | [Linting](/docs/python/linting.md) | +| ignorePatterns | `[".vscode/*.py", "**/site-packages/**/*.py"]` | Exclude file and folder patterns. | [Linting](/docs/python/linting.md) | + +### Pylint + +| Setting
(python.linting.) | Default | Description | See also | +| --- | --- | --- | --- | +| pylintEnabled | `true` | Specifies whether to enable Pylint. | [Linting](/docs/python/linting.md) | +| pylintArgs | `[]` | Additional arguments for Pylint, where each top-level element that's separated by a space is a separate item in the list. | [Linting](/docs/python/linting.md) | +| python.linting.pylintUseMinimalCheckers | `true` | Specifies whether to use the default value for pylintArgs. | [Linting](/docs/python/linting.md) | +| pylintPath | `"pylint"` | The path to Pylint. | [Linting](/docs/python/linting.md) | +| pylintCategorySeverity.convention | `"Information"` | Mapping for Pylint convention message to VS Code type. | [Linting](/docs/python/linting.md) | +| pylintCategorySeverity.refactor | `"Hint"` | Mapping for Pylint refactor message to VS Code type. | [Linting](/docs/python/linting.md) | +| pylintCategorySeverity.warning | `"Warning"` | Mapping for Pylint warning message to VS Code type. | [Linting](/docs/python/linting.md) | +| pylintCategorySeverity.error | `"Error"` | Mapping for Pylint error message to VS Code type. | [Linting](/docs/python/linting.md) | +| pylintCategorySeverity.fatal | `"Error"` | Mapping for Pylint fatal message to VS Code type. | [Linting](/docs/python/linting.md) | + +### Pep8/pycodestyle + +| Setting
(python.linting.) | Default | Description | See also | +| --- | --- | --- | --- | +| pep8Enabled | `false` | Specifies whether to enable pep8. | [Linting](/docs/python/linting.md) | +| pep8Args | `[]` | Additional arguments for pep8, where each top-level element that's separated by a space is a separate item in the list. | [Linting](/docs/python/linting.md) | +| pep8Path | `"pep8"` | The path to pep8. | [Linting](/docs/python/linting.md) | +| pep8CategorySeverity.W | `"Warning"` | Mapping for pep8 W message to VS Code type.| [Linting](/docs/python/linting.md) | +| pep8CategorySeverity.E | `"Error"` | Mapping for pep8 E message to VS Code type.| [Linting](/docs/python/linting.md) | + +### Flake8 + +| Setting
(python.linting.) | Default | Description | See also | +| --- | --- | --- | --- | +| flake8Enabled | `false` | Specifies whether to enable flake8. | [Linting](/docs/python/linting.md) | +| flake8Args | `[]` | Additional arguments for flake8, where each top-level element that's separated by a space is a separate item in the list. | [Linting](/docs/python/linting.md) | +| flake8Path | `"flake8"` | The path to flake8. | [Linting](/docs/python/linting.md) | +| flake8CategorySeverity.F | `"Error"` | Mapping for flake8 F message to VS Code type.| [Linting](/docs/python/linting.md) | +| flake8CategorySeverity.E | `"Error"` | Mapping for flake8 E message to VS Code type.| [Linting](/docs/python/linting.md) | +| flake8CategorySeverity.W | `"Warning"` | Mapping for flake8 W message to VS Code type.| [Linting](/docs/python/linting.md) | + +### mypy + +| Setting
(python.linting.) | Default | Description | See also | +| --- | --- | --- | --- | +| mypyEnabled | `false` | Specifies whether to enable mypy. | [Linting](/docs/python/linting.md) | +| mypyArgs | `["--ignore-missing-imports", "--follow-imports=silent"]` | Additional arguments for mypy, where each top-level element that's separated by a space is a separate item in the list. |[Linting](/docs/python/linting.md) | +| mypyPath | `"mypy"` | The path to mypy. | [Linting](/docs/python/linting.md) | +| mypyCategorySeverity.error | `"Error"` | Mapping for mypy error message to VS Code type. | [Linting](/docs/python/linting.md) | +| mypyCategorySeverity.note | `"Information"` | Mapping for mypy note message to VS Code type. | [Linting](/docs/python/linting.md) | + +### pydocstyle + +| Setting
(python.linting.) | Default | Description | See also | +| --- | --- | --- | --- | +| pydocstyleEnabled | `false` | Specifies whether to enable pydocstyle. | [Linting](/docs/python/linting.md) | +| pydocstyleArgs | `[]` | Additional arguments for pydocstyle, where each top-level element that's separated by a space is a separate item in the list. | [Linting](/docs/python/linting.md) | +| pydocstylePath | `"pydocstyle"` | The path to pydocstyle. | [Linting](/docs/python/linting.md) | + +### prospector + +| Setting
(python.linting.) | Default | Description | See also | +| --- | --- | --- | --- | +| prospectorEnabled | `false` | Specifies whether to enable prospector. | [Linting](/docs/python/linting.md) | +| prospectorArgs | `[]` | Additional arguments for prospector, where each top-level element that's separated by a space is a separate item in the list. | [Linting](/docs/python/linting.md) | +| prospectorPath | `"prospector"` | The path to prospector. | [Linting](/docs/python/linting.md) | + +### pylama + +| Setting
(python.linting.) | Default | Description | See also | +| --- | --- | --- | --- | +| pylamaEnabled | `false` | Specifies whether to enable pylama. | [Linting](/docs/python/linting.md) | +| pylamaArgs | `[]` | Additional arguments for pylama, where each top-level element that's separated by a space is a separate item in the list. | [Linting](/docs/python/linting.md) | +| pylamaPath | `"pylama"` | The path to pylama. | [Linting](/docs/python/linting.md) | + +## Unit testing settings + +### UnitTest framework + +| Setting
(python.unitTest.) | Default | Description | See also | +| --- | --- | --- | --- | +| unittestEnabled | `false` | Specifies whether UnitTest is enabled for unit testing. | [Unit testing](/docs/python/unit-testing.md) | +| unittestArgs | `["-v", "-s", ".", "-p", "*test*.py"]` | Arguments to pass to unittest, where each top-level element that's separated by a space is a separate item in the list. | [Unit testing](/docs/python/unit-testing.md) | +| cwd | null | Specifies an optional working directory for unit tests. | +| outputWindow | `"Python Test Log"` | The window to use for unit test output. | [Unit testing](/docs/python/unit-testing.md) | [Unit testing](/docs/python/unit-testing.md) | +| promptToConfigure | `true` | Specifies whether VS Code prompts to configure a test framework if potential tests are discovered. | [Unit testing](/docs/python/unit-testing.md) | +| debugPort | `3000` | Port number used for debugging of UnitTest tests. | [Unit testing](/docs/python/unit-testing.md) | + autoTestDiscoverOnSaveEnabled | `true` | Specifies whether to enable or disable auto run test discovery when saving a unit test file. | + +### PyTest framework + +| Setting
(python.unitTest.) | Default | Description | See also | +| --- | --- | --- | --- | +| pyTestEnabled | `false` | Specifies whether pytest is enabled for unit testing. | [Unit testing](/docs/python/unit-testing.md) | +| pyTestPath | `"py.test"` | Path to pytest. Use a full path if pytest is located outside the current environment. | [Unit testing](/docs/python/unit-testing.md) | +| pyTestArgs | `[]` | Arguments to pass to PyTest, where each top-level element that's separated by a space is a separate item in the list. When debugging unit tests with pytest-cov installed, include `--no-cov` in these arguments. | [Unit testing](/docs/python/unit-testing.md) | + +### Nose framework + +| Setting
(python.unitTest.) | Default | Description | See also | +| --- | --- | --- | --- | +| nosetestsEnabled | `false` | Specifies whether Nose is enabled for unit testing. | [Unit testing](/docs/python/unit-testing.md) | +| nosetestPath | `"nosetests"` | Path to Nose. Use a full path if PyTest is located outside the current environment. | [Unit testing](/docs/python/unit-testing.md) | +| nosetestArgs | `[]` | Arguments to pass to Nose, where each top-level element that's separated by a space is a separate item in the list. | [Unit testing](/docs/python/unit-testing.md) | + +## Next steps + +- [Python environments](/docs/python/environments.md) - Control which Python interpreter is used for editing and debugging. +- [Editing code](/docs/python/editing.md) - Learn about autocomplete, IntelliSense, formatting, and refactoring for Python. +- [Linting](/docs/python/linting.md) - Enable, configure, and apply a variety of Python linters. +- [Debugging](/docs/python/debugging.md) - Learn to debug Python both locally and remotely. +- [Unit testing](/docs/python/unit-testing.md) - Configure unit test environments and discover, run, and debug tests. diff --git a/docs/python/tutorial-deploy-app-service-on-linux.md b/docs/python/tutorial-deploy-app-service-on-linux.md new file mode 100644 index 0000000000000000000000000000000000000000..cf66afc18b8434563e616951344578c985f8d13b --- /dev/null +++ b/docs/python/tutorial-deploy-app-service-on-linux.md @@ -0,0 +1,301 @@ +--- +Order: 10 +Area: python +TOCTitle: Deploy to Azure App Service +ContentId: 1d4ae3ac-5d53-4e29-bf70-d97f1186c6c2 +PageTitle: Deploy Python web apps to Azure App Service on Linux +DateApproved: 01/14/2019 +MetaDescription: How to deploy Python web apps to Azure App Service on Linux +MetaSocialImage: images/tutorial/social.png +--- +# Deploy to Azure App Service on Linux + +This tutorial walks you through using Visual Studio Code to deploy a Python application to Azure App Service on Linux using the [Azure App Service](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) extension. + +[Azure App Service on Linux](https://docs.microsoft.com/azure/app-service/containers/app-service-linux-intro), currently in Preview for Python, runs your source code in a pre-defined Docker container. The characteristics of this container are summarized as follows (for full documentation, see [Configure Python apps for App Service on Linux](https://docs.microsoft.com/azure/app-service/containers/how-to-configure-python)): + +- Apps are run with Python 3.7 using the [Gunicorn](https://gunicorn.org) web server. +- The container includes [Flask](https://http://flask.pocoo.org) by default but not [Django](https://www.djangoproject.com). +- To install Django and any other dependencies, you **must** provide a `requirements.txt` file and deploy to App Service using Git, as shown in this tutorial. +- Although the container can run Django and Flask apps automatically, provided the app matches an expected structure, you can also provide a custom startup command file through which you have full control over the Gunicorn command line. A custom startup command is typically required for Flask apps, but not Django apps. +- The container definition itself is on the [github.com/Azure-App-Service/python](https://github.com/Azure-App-Service/python/tree/master/3.7.0). + +If you encounter any problems in the course of this tutorial, feel free to file an issue in the [Visual Studio Code documentation repository](https://github.com/Microsoft/vscode-docs/issues). + +## Prerequisites + +To complete this tutorial, you need an Azure account, Visual Studio Code with the Azure App Service extension, a Python environment, and an app that you'd like to deploy. + +### Azure account + +If you don't have an Azure account, [sign up now](https://azure.microsoft.com/free/?utm_source=campaign&utm_campaign=vscode-tutorial-docker-extension&mktingSource=vscode-tutorial-docker-extension) for a free 30-day account with $200 in Azure credits to try out any combination of services. + +### Visual Studio Code, Python, and the Azure App Service extension + +Install the following software: + +- [Visual Studio Code](https://code.visualstudio.com/). +- Python and the [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) extension as described on [Python Tutorial - Prerequisites](/docs/python/python-tutorial.md). +- The [Azure App Service](vscode:extension/ms-azuretools.vscode-azureappservice) extension, which provides interaction with Azure App Service from within VS Code. For general information, explore the [App Service extension tutorial](/tutorials/app-service-extension/getting-started.md) and visit the [vscode-azureappservice GitHub repository](https://github.com/Microsoft/vscode-azureappservice). + +### Sign in to Azure + +Once the App Service extension is installed, sign into your Azure account by navigating to the **Azure: App Service** explorer, select **Sign in to Azure**, and follow the prompts. + +![Sign in to Azure through VS Code](images/deploy-azure/azure-sign-in.png) + +After signing in, verify that you see the email account of your Azure around in the Status Bar and your subscription(s) in the **Azure: App Service** explorer: + +![VS Code status bar showing Azure account](images/deploy-azure/azure-account-status-bar.png) + +![VS Code Azure App Service explorer showing subscriptions](images/deploy-azure/azure-subscription-view.png) + +> **Note**: If you see the error **"Cannot find subscription with name [subscription ID]"**, this may be because you are behind a proxy and unable to reach the Azure API. Configure `HTTP_PROXY` and `HTTPS_PROXY` environment variables with your proxy information in your terminal: +> +> ```sh +> # macOS/Linux +> export HTTPS_PROXY=https://username:password@proxy:8080 +> export HTTP_PROXY=http://username:password@proxy:8080 +> +> #Windows +> set HTTPS_PROXY=https://username:password@proxy:8080 +> set HTTP_PROXY=http://username:password@proxy:8080 +> ``` + +### Your application + +If you don't already have an app you'd like to work with, use one of the options below. Be sure to verify that the app runs locally. + +- Create a new folder, open it in VS Code, and add a file named `hello.py` with the contents below, which creates a minimal Flask app as used in this walkthrough. The app object is purposely named `myapp` to demonstrate how the names are used in the startup command for the App Service, as you see later. + + Also follow the instructions in [Flask Tutorial - Create a project environment for Flask](/docs/python/tutorial-flask.md#create-a-project-environment-for-flask) to create a virtual environment with Flask installed within which you can run the app locally. + + ```python + from flask import Flask + myapp = Flask(__name__) + + @myapp.route("/") + def hello(): + return "Hello Flask, on Azure App Service for Linux" + ``` + +- [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial), which is the result of following the [Flask Tutorial](/docs/python/tutorial-flask.md). + +- [python-sample-vscode-django-tutorial](https://github.com/Microsoft/python-sample-vscode-django-tutorial), which is the result of following the [Django Tutorial](/docs/python/tutorial-django.md). + + > **Caveat**: If your Django app uses a local SQLite database like this sample, you need to include a pre-initialized and pre-populated copy of the `db.sqlite3` file in your repository. The reason for this is that, at present, the preview of App Service for Linux doesn't have a means to run Django's `migrate` command as part of deployment, so you must deploy a pre-made database. Even then, the database is effectively read-only; writing to the database also causes errors. The workaround is to use a database that's hosted elsewhere, in which case you would deploy and initialize that database separately before deploying the app code as described in this tutorial. + +## Create the App Service + +1. In the **Azure: App Service** explorer, select the **+** command to create a new App Service, or open the Command Palette and select **Azure App Service: Create New Web App**. (In App Service terminology, a "web app" is a **host** for web app code, not the app code itself.) + + ![Create new App Service button in the App Service explorer](images/deploy-azure/app-service-create-new.png) + +1. In the prompts that follow: + + - Enter a name for your app, which must be globally unique on App Service; typically you use your name or company name followed by the app name. + - Select **Linux** for the operating system. + - Select **[Preview] Python 3.7** as the runtime. + +1. After a short time you see a message that the new App Service was created, along with the question **Deploy to web app?**. Answer **No** at this point because you need to change the deployment source to Git. Otherwise the "Deploy to Web App" command only copies your files to the server using a ZIP file and doesn't install your dependencies. + + ![Messages that appear after the App Service is created](images/deploy-azure/app-service-created.png) + +1. To confirm that the App Service is running properly, expand your subscription in the **Azure: App Service** explorer, right-click the App Service name, and select **Browse website**: + + ![Browse Website command on an App Service in the App Service explorer](images/deploy-azure/browse-website-command.png) + +1. Because you haven't deployed your own code to the App Service yet, you should see only the default app: + + ![Default Python app on App Service on Linux](images/deploy-azure/default-python-app.png) + +## Configure a custom startup file + +Depending on how you've structured your app, you may need to create a custom startup command file for your app as described on [Configure Python apps for App Service on Linux](https://docs.microsoft.com/azure/app-service/containers/how-to-configure-python) in the Azure docs. + +The specific use cases of a custom startup command are as follows: + +- You have a **Flask** app whose startup file and app object are named something *other* than `application.py` and `app`, respectively. In other words, unless you have an `application.py` in the root folder of your project, *and* the Flask app object is named `app`, then you need a custom startup command. +- You want to start the Gunicorn web server with additional arguments beyond the defaults, which are `--bind=0.0.0.0 --timeout 600`. + +Django apps typically don't need customizations unless you want to provide additional arguments to Gunicorn. + +If you need a custom startup file, first create the file and commit it to your repository so it can be deployed with the rest of the app code. + +1. Create a file in your project named `startup.txt` (or another name of your choice) that contains your startup command. For Flask, see [Flask startup commands](#flask-startup-commands) in the next section. + +1. In the **Azure: App Service** explorer, expand the App Service, right-click **Application Settings**, and select **Open in Portal**: + + ![Open Settings in Portal command in the App Service explorer](images/deploy-azure/open-settings-in-portal-command.png) + +1. In the Azure portal, sign in if necessary; then on the **Application settings** page, enter your startup file name (like `startup.txt`) under **Runtime** > **Startup File**, then select **Save**. (This step is the one case in which you need to visit the Azure portal.) + + ![Setting the startup file name in the Azure portal](images/deploy-azure/azure-portal-startup-file.png) + +1. The App Service restarts when you save changes. Because you still haven't deployed your app code, however, visiting the site at this point shows "Application Error." This message indicates that the Gunicorn server started but failed to find the app, and therefore nothing is responding to HTTP requests. + +> **Note**: Instead of using a startup command file, you can also put the startup command directly in the **Startup File** field on the Azure portal. Using a file is generally preferable, however, as it keeps this bit of configuration in your repository where you can audit changes and redeploy to a different App Service instance altogether. + +### Flask startup commands + +By default, the App Service on Linux container assumes that a Flask app's startup file is named `application.py` and resides in the app's root folder. It further assumes that the Flask app object defined within that file is named `app`. If your app isn't structured in this exact way, then your custom startup command must identify the app object's location: + +1. **Different file name and/or app object name**: for example, if the app's startup file is `hello.py`and the app object is named `myapp`, the startup command is as follows: + + ```text + gunicorn --bind=0.0.0.0 --timeout 600 hello:myapp + ``` + +1. **Startup file is in a subfolder**: for example, if the startup file is `myapp/website.py` and the app object is `app`, then use Gunicorn's `--chdir` argument to specify the folder and then name the startup file and app object as usual: + + ```text + gunicorn --bind=0.0.0.0 --timeout 600 --chdir myapp website:app + ``` + +1. **Startup file is within a module**: in the [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial) code, the `webapp.py` startup file is contained within the folder `hello_app`, which is itself a module with an `__init__.py` file. The app object is named `app` and is defined in `__init__.py` and `webapp.py` uses a relative import. Because of this arrangement, pointing Gunicorn to `webapp:app` produces the error, "Attempted relative import in non-package," and the app fails to start. + + In this situation, create a simple shim file that imports the app object from the module, and then have Gunicorn launch the app using the shim. The [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial) code, for example, contains `startup.py` with the following contents: + + ```python + # startup.py shim + from hello_app.webapp import app + ``` + + The startup command is then the following: + + ```text + gunicorn --bind=0.0.0.0 --timeout 600 startup:app + ``` + +## Add the app to a Git repository + +As noted earlier, you must deploy to App Service on Linux using Git in order for the container to install your dependencies in `requirements.txt`. The following steps make sure you have both a `requirements.txt` file and a repository: + +1. Create a `requirements.txt` file in your root folder if you don't have one already: + + 1. Activate your virtual environment with the **Python: Select Interpreter** command on the **Command Palette** (`kb(workbench.action.showCommands)`). + 1. Open a terminal for the environment with **Terminal: Create New Integrated Terminal**. + 1. Make sure you're in the root folder of the app, then run `pip freeze > requirements.txt`. + +1. In your project folder, create a file named `.gitignore` with the following contents (change `.venv` if you're using a different folder for a virtual environment): + + ```gitignore + .vscode/ + __pycache__ + .venv/ + ``` + +1. From the **Command Palette**, run the **Git: Initialize Repository** command. + + ![Initialize repository command in the Command Palette](images/deploy-azure/source-control-initialize-repository-command.png) + + The same command is found at the top of the **Source Control** explorer: + + ![Initialize repository command in the Source Control explorer](images/deploy-azure/source-control-initialize-repository-button.png) + +1. In the prompt that appears, select your current folder for the repository, then answer **Open Repository** in the subsequent message" + + ![Selecting a repository folder](images/deploy-azure/source-control-select-folder.png) + + ![Opening the repository after initialization](images/deploy-azure/source-control-open-repository.png) + +1. In the Source Control explorer, you see your project files ready to commit to the repository. Enter a commit message like "Initial commit", then select the checkmark button: + + ![Commit the app code to source control](images/deploy-azure/source-control-commit.png) + +## Deploy your app using Git + +As mentioned earlier, you must use Git to deploy Python apps to App Service on Linux so that your dependencies in `requirements.txt` are installed. With Git deploy you can use either a local repository or a GitHub repository. + +1. Make sure all your code changes are committed to your repository, and pushed to GitHub if you're using that option. + +1. In the **Azure: App Service** explorer, right-click the App Service name, and select **Configure Deployment Source**: + + ![Configure Deployment Source command on an App Service in the App Service explorer](images/deploy-azure/configure-deployment-source.png) + +1. When prompted, choose either **LocalGit** or **GitHub** as the source: + + - **LocalGit**: code is deployed from the currently active branch of your local copy of the repository. + + - **GitHub**: code is deployed from the selected branch of a GitHub repository, and happens automatically when you push commits to the repository. Selecting this option successively prompts you for the organization, repository, and branch to use. + +1. With both choices, the extension connects the App Service to the repository. You don't see indications of the connection in VS Code itself; on the Azure portal, you can examine the connect on the Azure portal in the App Service's **Deployment Center** page. + +1. To deploy the app: + + - **LocalGit**: Commit your changes to your local repository, then right-click the App Service again, select **Deploy to Web App**, and select the project folder when prompted. (You can also select the deploy button at the top of the explorer.) + + ![Deploy to Web App command on an App Service in the App Service explorer](images/deploy-azure/deploy-to-web-app-command.png) + + - **GitHub**: Commit your changes, then do a Git push by selecting **Git: Push** from the Command Palette or by using the sync changes button on the status bar: + + ![Git sync changes button on the VS Code status bar](images/deploy-azure/git-sync-changes.png) + +1. While deployment is taking place, you see an indicator in the App Service extension explorer: + + ![Deployment indicator in the App Service extension explorer](images/deploy-azure/deployment-underway.png) + + You can also observe progress in the **Output** panel (`kb(workbench.action.output.toggleOutput)`) by selecting **Azure App Service** from the drop-down: + + ![Observing App Service output in the Output window](images/deploy-azure/app-service-output.png) + +1. After a minute or two (depending on how many dependencies are in your `requirements.txt`), VS Code reports that deployment is complete. To verify that your files are deployed, expand the App Service in the **Azure: App Service** explorer, then expand **Files**: + + ![Checking deployment files through the App Service explorer](images/deploy-azure/expand-files-node.png) + + The `antenv` folder is where App Service creates a virtual environment with your dependencies. If you expand this node, you can verify that the packages you named in `requirements.txt` are installed in `antenv/lib/python3.7/site-packages`. + +1. Right-click the App Service again and select **Browse Website** to view your running app (you may need to refresh the browser if the previous page was cached): + + ![The app running successfully on App Service](images/deploy-azure/running-app.png) + +## Make changes and redeploy + +With your App Service connected to a repository, you have a simple code-test-deploy process: + +1. Make changes and test the app locally. + +1. Commit changes to your Git repository. Always remember this step, because the App Service extension pulls your code from the repository and won't pick up uncommitted changes! + +1. Deploy the code: + + 1. **LocalGit**: open the **Azure: App Service** explorer, right-click the App Service, and select **Deploy to Web App**. + 1. **GitHub**: push your changes to GitHub; App Service automatically deploys the code and restarts. + +1. Once deployment is complete, wait a few seconds for the App Service to restart, then browse the website and verify your changes. + +With any deployment option, you can observe status on the Azure portal under the App Service's **Deployment** > **Deployment options** page: + +![Azure portal showing deployment status for an App Service](images/deploy-azure/deployment-options-status.png) + +### Changing the GitHub branch + +When you use the App Service extension in VS Code to set GitHub as the deployment source, you're prompted for a specific branch. This branch is then directly wired into the App Service configuration. To use a different branch, you must first disconnect the existing branch, then create a new connection: + +1. In the **App Service** explorer in VS Code, right-click the App Service and select **Open in portal**. +1. On the portal, select **Deployment** > **Deployment options**, then select **Disconnect**. + + ![Disconnecting a deployment source](images/deploy-azure/deployment-options-disconnect.png) + +1. Once disconnected, you can configure a new connection directly on the portal, or you can use the App Service extension in VS Code to set the deployment source to GitHub again, selecting the desired branch. + +## Next steps + +Congratulations on completing this walkthrough of deploying Python code to App Service on Linux! + +As noted earlier, you can learn more about the App Service extension by visiting its GitHub repository, [vscode-azureappservice](https://github.com/Microsoft/vscode-azureappservice). Issues and contributions are also welcome. + +To learn more about Azure services that you can use from Python, including data storage along with AI and Machine Learning services, visit [Azure Python Developer Center](https://docs.microsoft.com/python/azure/?view=azure-python). + +There are also other Azure extensions for VS Code that you may find helpful. Just search on "Azure" in the Extensions explorer: + +![Azure extensions for VS Code](images/deploy-containers/azure-extensions.png) + +A few favorites include: + +- [Cosmos DB](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb) +- [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) +- [Azure CLI Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azurecli) +- [Azure Resource Manager (ARM) Tools](https://marketplace.visualstudio.com/items?itemName=msazurermtools.azurerm-vscode-tools) + +And again, if you've encountered any problems in the course of this tutorial, feel free to file an issue in the [VS Code docs repo](https://github.com/Microsoft/vscode-docs/issues). diff --git a/docs/python/tutorial-deploy-containers.md b/docs/python/tutorial-deploy-containers.md new file mode 100644 index 0000000000000000000000000000000000000000..2ad1d6c1b90ac265b315b5529ff7b35609091a60 --- /dev/null +++ b/docs/python/tutorial-deploy-containers.md @@ -0,0 +1,406 @@ +--- +Order: 11 +Area: python +TOCTitle: Deploy with containers +ContentId: e3f4006c-ab3f-4444-909b-fb045afcdf09 +PageTitle: Deploy Python web apps to Azure App Service using Docker containers +DateApproved: 01/14/2019 +MetaDescription: How to create Docker containers for Python web apps and deploy to Azure App Service +MetaSocialImage: images/tutorial/social.png +--- +# Deploy Python using Docker containers + +This tutorial walks you through the full process of containerizing an existing Python application using [Docker](https://www.docker.com/), pushing the app image to a Docker registry, then deploying the image to [Azure App Service](https://azure.microsoft.com/services/app-service/containers/), all within Visual Studio Code. The tutorial also demonstrates how to use base container images that include production-ready web servers (uwsgi and nginx), and how to configure those servers for both [Django](https://www.djangoproject.com/) and [Flask](http://flask.pocoo.org/) web apps, which is helpful to know no matter what your deployment target. + +If you have any problems, feel free to file an issue for this tutorial in the [VS Code documentation repository](https://github.com/Microsoft/vscode-docs/issues). + +## An introduction to containers + +Docker is a system that allows you to deploy and run apps using **containers** rather than setting up dedicated environments like virtual machines. A container is a lightweight runtime environment that shares the resources of the host operating system with other containers. Docker is the layer that sits above the operating system to manage resources on behalf of containers. + +A container is specifically an instance of a Docker **image**, an executable package that contains everything needed to run your app: app code, configuration files, runtimes, and all of app's dependencies. An image can be used to instantiate any number of identical containers, which is especially useful when scaling out a cloud-based web app. Because container images are much smaller than virtual machine images, instances can be started and stopped much more quickly than virtual machines, enabling your app to be highly responsive to varying loads at a minimal cost. (When used to scale web apps, containers are often managed in **clusters**, which are then managed by an orchestration agent such as [Kubernetes](https://wikipedia.org/wiki/Kubernetes).) + +Images, for their part, are built in multiple **layers**. The lowest or **base** layers of an image are typically common elements like the Python runtime; the higher layers the contain more specialized elements like your app code. Because of layering, it takes very little time to rebuild an image when changing only the top layer with your app code. Similarly, when you push an image to a **container registry**, an online repository for images from which you can deploy to cloud services like Azure, only the modified layers need be uploaded and redeployed. As a result, using containers has only a small impact on your develop-test-deploy loop. + +You will experience the basics of containers and images in the course of this tutorial. For additional background, including helpful diagrams, refer to the [Docker documentation](https://docs.docker.com/get-started/). + +## Prerequisites + +To complete this tutorial you need an Azure account, Docker, Visual Studio Code with the necessary extensions, a Python environment, and an app that you'd like to deploy using containers. + +### Azure account + +If you don't have an Azure account, [sign up now](https://azure.microsoft.com/free/?utm_source=campaign&utm_campaign=vscode-tutorial-docker-extension&mktingSource=vscode-tutorial-docker-extension) for a free 30-day account with $200 in Azure credits to try out any combination of services. + +### Visual Studio Code, Docker, and Python runtime + +Install the following software: + +- [Visual Studio Code](https://code.visualstudio.com/) +- [Docker Community Edition](https://www.docker.com/community-edition). To verify your installation, run the command `docker --version`, which should show output like `Docker version 18.06.1-ce, build e68fc7a`. +- Python and the Python extension as described on [Python Tutorial - Prerequisites](/docs/python/python-tutorial.md). + +### Docker and Azure App Service extensions for VS Code + +The **Docker extension** helps you manage local Docker images, provides Docker commands, and simplifies deployment of app images to Azure. You can find an overview of the extension on the [vscode-docker GitHub repository](https://github.com/Microsoft/vscode-docker). + +> Install the Docker extension + +The **Azure App Service extension** helps you create, manage, and deploy Web Apps to Azure App Service on Linux. For details, explore the [App Service extension tutorial](/tutorials/app-service-extension/getting-started.md) or visit the [vscode-azureappservice GitHub repository](https://github.com/Microsoft/vscode-azureappservice). + +> Install the Azure App Service extension + +### Sign in to Azure + +Once the extensions are installed, sign into your Azure account by navigating to the **Azure: App Service** explorer, select **Sign in to Azure**, and follow the prompts. + +![Sign in to Azure through VS Code](images/deploy-azure/azure-sign-in.png) + +After signing in, verify that you see the email account of your Azure around in the Status Bar and your subscription(s) in the **Azure: App Service** explorer: + +![VS Code status bar showing Azure account](images/deploy-azure/azure-account-status-bar.png) + +![VS Code Azure App Service explorer showing subscriptions](images/deploy-azure/azure-subscription-view.png) + +> **Note**: If you see the error **"Cannot find subscription with name [subscription ID]"**, this may be because you are behind a proxy and unable to reach the Azure API. Configure `HTTP_PROXY` and `HTTPS_PROXY` environment variables with your proxy information in your terminal: +> +> ```sh +> # macOS/Linux +> export HTTPS_PROXY=https://username:password@proxy:8080 +> export HTTP_PROXY=http://username:password@proxy:8080 +> +> #Windows +> set HTTPS_PROXY=https://username:password@proxy:8080 +> set HTTP_PROXY=http://username:password@proxy:8080 +> ``` + +### App code + +If you don't already have an app you'd like to work with, use one of the following samples, which already include the Docker-related files described later in this tutorial: + +- [python-sample-vscode-django-tutorial](https://github.com/Microsoft/python-sample-vscode-django-tutorial), which is the result of following the [Django Tutorial](/docs/python/tutorial-django.md). + +- [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial), which is the result of following the [Flask Tutorial](/docs/python/tutorial-flask.md). + +After verifying that your app runs properly, generate a `requirements.txt` file (using `pip freeze > requirements.txt`, for example) so that those dependencies can be automatically installed in the Docker image. The samples each include a `requirements.txt` file. + +## Create a container registry + +As mentioned earlier, a container registry is an online repository for container images that allows a cloud service, like Azure App Service, to acquire the image whenever it needs to start a container instance. Because the registry manages images separate from container instances, the same image in a registry can be used to start any number of concurrent instances, as happens when scaling out a web app to handle increased loads. + +Because setting up a registry is a one-time affair, you do that step now before creating images that you then push to that registry. + +Registry options include the following: + +- The [Azure Container Registry (ACR)](https://azure.microsoft.com/services/container-registry/), a private, secure, hosted registry for your images. +- [Docker Hub](https://hub.docker.com/), Docker's own hosted registry that provides a free way to share images. +- A private registry running on your own server, as described on [Docker registry](https://docs.docker.com/registry/) in the Docker documentation. + +To create an Azure Container Registry, as shown in this tutorial, do the following: + +1. Follow the first part of [Quickstart: Create a container registry using the Azure portal](https://docs.microsoft.com/azure/container-registry/container-registry-get-started-portal) through the "Log in to ACR" section. You don't need to complete the sections "Push image to ACR" and later because you do those steps within VS Code as part of this tutorial. + +1. Make sure that the registry endpoint you created is visible under **Registries** in the **Docker** explorer of VS Code: + + ![Docker explorer in VS Code showing registries](images/deploy-containers/registries.png) + +## Create a container image + +A container image is a bundle of your app code and its dependencies. To create an image, Docker needs a `Dockerfile` that describes how to structure the app code in the container and how to get that code running. The `Dockerfile`, in other words, is the template for your image. The Docker extension helps you create these files with customization for production servers. + +> **Note**: The Python samples linked earlier in this article already contain the necessary Docker files. The instructions here help you create files for an app of your own. + +## Create the Docker files + +1. In VS Code, open the **Command Palette** (`kb(workbench.action.showCommands)`) and select the **Docker: Add Docker files to workspace** command. + +1. When the prompt appears after a few moments, select **Python** as the app type. + +1. Specify the port on which your app listens, such as 8000 (as in the Django sample) or 5000 (as in the Flask sample). The port value ends up only in the Docker compose files (see below) and have no impact on your container image. + +1. With all this information, the Docker extension creates the following files: + + - The `Dockerfile` file describes the contents of your app's layer in the image. Your app layer is added on top of the base image indicated in the `Dockerfile`.. By default, the name of the image is the name of the workspace folder in VS Code. + + - A `.dockerignore` file that reduces image size by excluding files and folders that aren't needed in the image, such as `.git` and `.vscode`. For Python, add another line to the file for `__pycache__`. + + - `docker-compose.yml` and `docker-compose.debug.yml` files that are used with [Docker compose](https://docs.docker.com/compose/overview/). For the purposes of this tutorial, you can ignore or delete these files. + +> **Tip:** VS Code provides great support for Docker files. See the [Working with Docker](/docs/azure/docker.md) article to learn about rich language features like smart suggestions, completions, and error detection. + +## Using production servers + +For Python, the Docker extension by default specifies the base image `python:alpine` in the `Dockerfile` and includes commands to run only the Flask development server. These defaults obviously don't accommodate Django, for one, and when deploying to the cloud, as with Azure App Service, you should also use production-ready web servers instead of a development server. (If you're used Flask, you're probably accustomed to seeing the development server's warning in this regard!) + +For this reason, you need to modify the `Dockerfile` to use a base image with production servers, then provide the necessary configuration for your app. The following sections provide details for both Flask and Django. + +### Changes for Flask apps + +A good base image for Flask is `tiangolo/uwsgi-nginx-flask:python3.6-alpine3.7`, which is also available for other versions of Python (see the [tiangolo/uwsgi-nginx-flask repository](https://github.com/tiangolo/uwsgi-nginx-flask-docker) on GitHub). This image already contains Flask and the production-ready uwsgi and nginx servers. + +By default, the image assumes that (a) your app code is located in an `app` folder, (b) the Flask app object is named `app`, and (c) the app object is located in `main.py`. Because your app may have a different structure, you can indicate the correct folders in the Dockerfile and provide the necessary parameters the uwsgi server in a `uwsgi.ini` file. + +The following steps summarize the configuration used in the [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial) app, which you can adapt for your own code. + +1. The `Dockerfile` indicates the location and name of the Flask app object, the location of static files for nginx, and the location of the `uwsgi.ini` file. (The `Dockerfile` in the sample contains further explanatory comments that are omitted here.) + + ```dockerfile + FROM tiangolo/uwsgi-nginx-flask:python3.6-alpine3.7 + + ENV LISTEN_PORT=5000 + EXPOSE 5000 + + # Indicate where uwsgi.ini lives + ENV UWSGI_INI uwsgi.ini + + # Tell nginx where static files live. + ENV STATIC_URL /hello_app/static + + # Set the folder where uwsgi looks for the app + WORKDIR /hello_app + + # Copy the app contents to the image + COPY . /hello_app + + # If you have additional requirements beyond Flask (which is included in the + # base image), generate a requirements.txt file with pip freeze and uncomment + # the next three lines. + #COPY requirements.txt / + #RUN pip install --no-cache-dir -U pip + #RUN pip install --no-cache-dir -r /requirements.txt + ``` + +1. The `uwsgi.ini` file, which is in the `hello_app` folder of the sample, provides configuration arguments for the uwsgi server. For the sample, the configuration below says that the Flask app object is found in the `hello_app/webapp.py` module, and that it's named (that is, "callable" as) `app`. The other values are additional common uwsgi settings: + + ```ini + [uwsgi] + module = hello_app.webapp + callable = app + uid = 1000 + master = true + threads = 2 + processes = 4 + ``` + +### Changes for Django apps + +A good base image for Django is `tiangolo/uwsgi-nginx:python3.6-alpine3.7`, which is also available for other versions of Python (see the [tiangolo/uwsgi-nginx repository](https://github.com/tiangolo/uwsgi-nginx-docker) on GitHub). + +This base image already contains the production-ready uwsgi and nginx servers, but does not include Django. It's also necessary to provide settings to uwsgi so it can find the app's startup code. + +The following steps summarize the configuration used in the [python-sample-vscode-django-tutorial](https://github.com/Microsoft/python-sample-vscode-django-tutorial) app that you can adapt for your own code. + +1. Make sure you have a `requirements.txt` file in your project that contains Django and its dependencies. You can generate `requirements.txt` using the command `pip freeze > requirements.txt`. + +1. In your Django project's `settings.py` file, add the root URL to which you intend to deploy the app to the `ALLOWED_HOSTS` list. For example, the following code assumes deployment to an Azure App Service (azurewebsites.net) named "vsdocs-django-sample-container": + + ```python + ALLOWED_HOSTS = [ + # Example host name only; customize to your specific host + "vsdocs-django-sample-container.azurewebsites.net" + ] + ``` + + Without this entry, you'll eventually get all the way through the deployment only to see a "DisallowedHost" message that instructs to you add the domain to `ALLOWED_HOSTS`, which requires that you rebuild, push, and redeploy the image all over again! + +1. Create a `uwsgi.ini` file in the Django project folder (alongside `manage.py`) that contains startup arguments for the uwsgi server. In the sample, the Django project is in a folder called `web_project`, which is where the `wsgi.py` and `setting.py` files live. + + ```ini + [uwsgi] + chdir = . + module = web_project.wsgi:application + env = DJANGO_SETTINGS_MODULE=web_project.settings + uid = 1000 + master = true + threads = 2 + processes = 4 + ``` + +1. Modify the `Dockerfile` to indicate the location of `uwsgi.ini`, set the location of static files for nginx, and make sure the SQLite database file is writable. (The `Dockerfile` in the sample contains further explanatory comments that are omitted here.) + + ```dockerfile + FROM tiangolo/uwsgi-nginx:python3.6-alpine3.7 + + ENV LISTEN_PORT=8000 + EXPOSE 8000 + + # Indicate where uwsgi.ini lives + ENV UWSGI_INI uwsgi.ini + + # Tell nginx where static files live (as typically collected using Django's + # collectstatic command. + ENV STATIC_URL /app/static_collected + + # Copy the app files to a folder and run it from there + WORKDIR /app + ADD . /app + + # Make app folder writable for the sake of db.sqlite3, and make that file also writable. + RUN chmod g+w /app + RUN chmod g+w /app/db.sqlite3 + + # Make sure dependencies are installed + RUN python3 -m pip install -r requirements.txt + ``` + +> **Note**: When building a Docker image on Windows, you typically see the message below, which is why the Dockerfile shown here includes the two `chmod` commands. If need to make other files writable, add the appropriate `chmod` commands to your Dockerfile. +> +> ```output +> SECURITY WARNING: You are building a Docker image from Windows against a non-Windows Docker host. All files and directories added to build context will have '-rwxr-xr-x' permissions. It is recommended to double check and reset permissions for sensitive files and directories. +> ``` + +## Build and test the image + +With the necessary `Dockerfile` in place, you're ready to build the Docker image and run it locally: + +1. Make sure that Docker is running on your computer. + +1. On the VS Code **Command Palette** (`kb(workbench.action.showCommands)`), select **Docker: Build Image**. + +1. When prompted for the Docker file, choose the `Dockerfile` that you created in the previous section. (VS Code remembers your selection so you won't need to enter it again to rebuild.) + +1. When prompted for a name to give the image, use a name that follows the conventional form of `/:`, where `` is typically `latest`. Here are some examples: + + ```sh + # Examples for Azure Container Registry, prefixed with the registry name + vsdocsregistry.azurecr.io/python-sample-vscode-django-tutorial:latest + vsdocsregistry.azurecr.io/python-sample-vscode-flask-tutorial:latest + vsdocsregistry.azurecr.io/myexpressapp:latest + + # Examples for Docker hub, prefixed with your username + vsdocs-team/python-sample-vscode-django-tutorial:latest + vsdocs-team/python-sample-vscode-flask-tutorial:latest + vsdocs-team/myexpressapp:latest + ``` + +1. Each step of Docker's build process appears in the VS Code Terminal panel, including any errors that occur running the steps in the `Dockerfile`. + + > **Tip**: every time you run the **Docker: Build image** command, the Docker extension opens another Terminal in VS Code in which to run the command. You can close each terminal once the build is complete. Alternately, you can reuse the same terminal to build the image by scrolling up in the command history using the up arrow. + +1. When the build is complete, the image appears in the **Docker** explorer under **Images**: + + ![Docker Image](images/deploy-containers/image-list.png) + +1. Run and test your container locally by using the following command, replacing `` with your specific image, and changing the port numbers as needed. For web apps, you can then open browser to `localhost:` to see the running app. + + ```bash + # For Flask sample + docker run --rm -it -p 5000:5000 + + # For Django sample + docker run --rm -it -p 8000:8000 + ``` + +### Two useful features of the Docker extension + +The Docker extension provides a simple UI to manage and even run your images rather than using the Docker CLI. Just expand the **Image** node in the Docker explorer, right-click any image, and select any of the menu items: + +![Managing images with the Docker extension](images/deploy-containers/manage-images.png) + +In addition, on the top of the Docker explorer, next to the refresh button, is a button for **System Prune**. This command cleans up any dangling and otherwise unused images on your local computer. It's a good idea to periodically use the command to reclaim space on your file system. + +![System Prune command in the Docker explorer](images/deploy-containers/system-prune-command.png) + +## Push the image to a registry + +Once you're confident that your image works, the next step is to push it to your container registry: + +1. On the **Command Palette** (`kb(workbench.action.showCommands)`), select **Docker: Push**. + +1. Choose the image you just built to push the image to the registry; upload progress appears in the Terminal. + +1. Once completed, expand the **Registries** > **Azure** (or **DockerHub**) node in the **Docker** explorer, then expand the registry and image name to see the exact image. (You may need to refresh the **Docker** explorer.) + + ![The built app image in the Azure Container Registry](images/deploy-containers/image-in-acr.png) + +> **Tip:** The first time you push an image, you see that VS Code uploads all of the different layers that make up the image. Subsequent push operations, however, upload only those layers that have changed. Because it's typically only your app code that's changes, those uploads happen much more quickly, making for a tight edit-build-deploy-test loop. To see this, make a small change to your code, rebuild the image, and then push again to the registry. The whole process typically completes in a matter of seconds. + +## Deploy the image to Azure + +With an image built and pushed to a registry, you can use the Docker extension in VS Code to easily set up an Azure App Service running the container. + +1. In the **Docker** explorer, expand **Registries** > **Azure**, then expand your registry node and the image name until you see the image with the `:latest` tag. + + ![Locating an image in the Docker explorer](images/deploy-containers/deploy-find-image.png) + +1. Right-click the image and select **Deploy Image to Azure App Service**. + + ![Selecting the Deploy menu command](images/deploy-containers/deploy-menu.png) + +1. Follow the prompts to select an Azure subscription, select or specify a resource group, specify a region, configure an App Service Plan (B1 is the least expensive), and specify a name for the site. The animation below illustrates the process. + + ![Create and Deploy](images/deploy-containers/deploy-to-app-service.gif) + + A **Resource Group** is a named collection the different resources that make up an app. By assigning all the app's resources to a single group, you can easily manage those resources as a single unit. (For more information, see the [Azure Resource Manager overview](https://docs.microsoft.com/azure/azure-resource-manager/resource-group-overview) in the Azure documentation.) + + An **App Service Plan** defines the physical resources (an underlying virtual machine) that hosts the running container. For this tutorial, B1 is the least expensive plan that supports Docker containers. (For more information, see [App Service plan overview](https://docs.microsoft.com/azure/app-service/azure-web-sites-web-hosting-plans-in-depth-overview) in the Azure documentation.) + + The name of the App Service must be unique across all of Azure, so you typically use a company or personal name. For production sites, you typically configure the App Service with a separately registered domain name. + +1. Creating the app service takes a few minutes, and you see progress in VS Code's Output panel. + +1. Once completed, you **must** also add a setting named `WEBSITES_PORT` (notice the plural "WEBSITES") to the App Service to specify the port on which the container is listening, such as 5000 (in the Flask sample) or 8000 (in the Django sample). To do this, switch to the **Azure: App Service** explorer, expand the node for your new App Service (refresh if necessary), then right-click **Application Settings** and select **Add New Setting**. At the prompts enter `WEBSITES_PORT` as the key and the port number for the value. + + ![Context menu command on an App Service for Add New Setting](images/deploy-containers/add-app-service-setting.png) + +1. The App Service restarts automatically when you change settings. You can also right-click the App Service and select **Restart** at any time. + +1. After the service has restarted, browse the site at `http://.azurewebsites.net`. You can `kbstyle(Ctrl+click)` the URL in the Output panel, or right-click the App Service in the **Azure: App Service** explorer and select **Browse Website**. + +## Make changes and redeploy + +Because you inevitably make changes to your app, you end up rebuilding and redeploying your container many times. Fortunately, the process is simple: + +1. Make changes to your app and test locally. + +1. Rebuild the Docker image. If you change only app code, the build should take only a few seconds. + +1. Push your image to the registry. If again you change nothing but app code, only that small layer needs to be pushed and the process typically completes in a few seconds. + +1. In the **Azure: App Service** explorer, right-click the appropriate App Service and select **Restart**. Restarting an app service automatically pulls the latest container image from the registry. + +1. After about 15-20 seconds, visit the App Service URL again to check the updates. + +## Viewing logs + +From within VS Code, you can view (or "tail") logs from the running site on Azure App Service, which captures any output to the console as from `print` statements and routes them to the VS Code **Output** panel. + +1. Find the app in the **Azure: App Service** explorer, right-click the app, and choose **Start Streaming Logs**. + +1. Answer **Yes** when prompted to enable logging and restart the app. Once the app is restarted, the VS Code Output panel opens with a connection to the log stream. + +1. After a few seconds, you see a message indicating that you are connected to the log-streaming service. + + ```bash + Connecting to log stream... + 2018-09-27T20:14:26 Welcome, you are now connected to log-streaming service. + + 2018-09-27 20:14:59.269 INFO - Starting container for site + + 2018-09-27 20:14:59.270 INFO - docker run -d -p 24138:8000 --name vsdocs-django-sample-container_0 -e WEBSITES_PORT=8000 -e WEBSITE_SITE_NAME=vsdocs-django-sample-container -e WEBSITE_AUTH_ENABLED=False -e WEBSITE_ROLE_INSTANCE_ID=0 -e WEBSITE_INSTANCE_ID=02c705ae24eaf5f298e553a9c2724b9fe4485707c2d1c36137cd02931091e561 -e HTTP_LOGGING_ENABLED=1 vsdocsregistry.azurecr.io/python-sample-vscode-django-tutorial:latest + + 2018-09-27 20:15:06.216 INFO - Container vsdocs-django-sample-container_0 for site vsdocs-django-sample-container initialized successfully. + ``` + +1. Navigate within the app to see additional output for various HTTP requests. + +## Next steps + +Congratulations on completing this walkthrough of deploying a containerized Python app to Azure App Service! + +As noted earlier, you can learn more about the Docker and App Service extensions by visiting their respective repositories on GitHub: [vscode-docker](https://github.com/Microsoft/vscode-docker) and [vscode-azureappservice](https://github.com/Microsoft/vscode-azureappservice). Issues and contributions are also welcome. + +To learn more about Azure services that you can use from Python, including data storage along with AI and Machine Learning services, visit [Azure Python Developer Center](https://docs.microsoft.com/python/azure/?view=azure-python). + +There are also other Azure extensions for VS Code that you may find helpful. Just search on "Azure" in the Extensions explorer: + +![Azure extensions for VS Code](images/deploy-containers/azure-extensions.png) + +A few favorites include: + +- [Cosmos DB](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb) +- [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) +- [Azure CLI Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azurecli) +- [Azure Resource Manager (ARM) Tools](https://marketplace.visualstudio.com/items?itemName=msazurermtools.azurerm-vscode-tools) + +And again, if you've encountered any problems in the course of this tutorial, feel free to file an issue for this tutorial in the [VS Code documentation repository](https://github.com/Microsoft/vscode-docs/issues). diff --git a/docs/python/tutorial-django.md b/docs/python/tutorial-django.md new file mode 100644 index 0000000000000000000000000000000000000000..b79cca20c119f1862cf04af915f8364a7c8363fa --- /dev/null +++ b/docs/python/tutorial-django.md @@ -0,0 +1,944 @@ +--- +Order: 8 +Area: python +TOCTitle: Django Tutorial +ContentId: 3c0948f9-85a5-4dd4-a461-59788dbfce4c +PageTitle: Python and Django tutorial in Visual Studio Code +DateApproved: 03/07/2019 +MetaDescription: Python Django tutorial demonstrating IntelliSense, code navigation, and debugging for both code and templates in Visual Studio Code, the best Python IDE. +--- +# Django Tutorial in Visual Studio Code + +[Django](https://www.djangoproject.com/) is a high-level Python framework designed for rapid, secure, and scalable web development. Django includes rich support for URL routing, page templates, and working with data. + +In this Django tutorial, you create a simple Django app with three pages that use a common base template. You create this app in the context of Visual Studio Code in order to understand how to work with Django in the VS Code terminal, editor, and debugger. This tutorial does not explore various details about Django itself, such as working with data models and creating an administrative interface. For guidance on those aspects, refer to the [Django documentation](https://docs.djangoproject.com/en/2.1/intro/tutorial01/). + +The completed code project from this Django tutorial can be found on GitHub: [python-sample-vscode-django-tutorial](https://github.com/Microsoft/python-sample-vscode-django-tutorial). + +If you have any problems, feel free to file an issue for this tutorial in the [VS Code documentation repository](https://github.com/Microsoft/vscode-docs/issues). + +## Prerequisites + +To successfully complete this Django tutorial, you must do the following (which are the same steps as in the [general Python tutorial](/docs/python/python-tutorial.md)): + +1. Install the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python). + +1. Install a version of Python 3 (for which this tutorial is written). Options include: + - (All operating systems) A download from [python.org](https://www.python.org/downloads/); typically use the **Download Python 3.7.0** button that appears first on the page (or whatever is the latest version). + - (Linux) The built-in Python 3 installation works well, but to install other Python packages you must run `sudo apt install python3-pip` in the terminal. + - (macOS) An installation through [Homebrew](https://brew.sh/) on macOS using `brew install python3` (the system install of Python on macOS is not supported). + - (All operating systems) A download from [Anaconda](https://www.anaconda.com/download/) (for data science purposes). + +1. On Windows, make sure the location of your Python interpreter is included in your PATH environment variable. You can check the location by running `path` at the command prompt. If the Python interpreter's folder isn't included, open Windows Settings, search for "environment", select **Edit environment variables for your account**, then edit the **Path** variable to include that folder. + +## Create a project environment for the Django tutorial + +In this section, you create a virtual environment in which Django is installed. Using a virtual environment avoids installing Django into a global Python environment and gives you exact control over the libraries used in an application. A virtual environment also makes it easy to [Create a requirements.txt file for the environment](#create-a-requirementstxt-file-for-the-environment). + +1. On your file system, create a project folder for this tutorial, such as `hello_django`. + +1. In that folder, use the following command (as appropriate to your computer) to create a virtual environment named `env` based on your current interpreter: + + ```bash + # macOS/Linux + sudo apt-get install python3-venv # If needed + python3 -m venv env + + # Windows + python -m venv env + ``` + + > **Note**: Use a stock Python installation when running the above commands. If you use `python.exe` from an Anaconda installation, you see an error because the ensurepip module isn't available, and the environment is left in an unfinished state. + +1. Open the project folder in VS Code by running `code .`, or by running VS Code and using the **File** > **Open Folder** command. + +1. In VS Code, open the Command Palette (**View** > **Command Palette** or (`kb(workbench.action.showCommands)`)). Then select the **Python: Select Interpreter** command: + + ![Django tutorial: opening the Command Palette in VS Code](images/shared/command-palette.png) + +1. The command presents a list of available interpreters that VS Code can locate automatically (your list will vary; if you don't see the desired interpreter, see [Configuring Python environments](/docs/python/environments.md)). From the list, select the virtual environment in your project folder that starts with `./env` or `.\env`: + + ![Django tutorial: Selecting the virtual environment for Python](images/shared/select-virtual-environment.png) + +1. Run **Terminal: Create New Integrated Terminal** (`kb(workbench.action.terminal.new)`) from the Command Palette, which creates a terminal and automatically activates the virtual environment by running its activation script. + + > **Note**: On Windows, if your default terminal type is PowerShell, you may see an error that it cannot run activate.ps1 because running scripts is disabled on the system. The error provides a link for information on how to allow scripts. Otherwise, use **Terminal: Select Default Shell** to set "Command Prompt" or "Git Bash" as your default instead. + +1. The selected environment appears on the left side of the VS Code status bar, and notice the "(venv)" indicator that tells you that you're using a virtual environment: + + ![Django tutorial: selected environment showing in the VS Code status bar](images/shared/environment-in-status-bar.png) + +1. Install Django in the virtual environment by running one of the following commands in the VS Code Terminal: + + ```bash + python -m pip install django + ``` + +You now have a self-contained environment ready for writing Django code. VS Code activates the environment automatically when you use **Terminal: Create New Integrated Terminal**. If you open a separate command prompt or terminal, activate the environment by running `source env/bin/activate` (Linux/macOS) or `env\scripts\activate` (Windows). You know the environment is activated when the command prompt shows **(env)** at the beginning. + +## Create and run a minimal Django app + +In Django terminology, a "Django project" is composed of several site-level configuration files along with one or more "apps" that you deploy to a web host to create a full web application. A Django project can contain multiple apps, each of which typically has an independent function in the project, and the same app can be in multiple Django projects. An app, for its part, is just a Python package that follows certain conventions that Django expects. + +To create a minimal Django app, then, it's necessary to first create the Django project to serve as the container for the app, then create the app itself. For both purposes, you use the Django administrative utility, `django-admin`, which is installed when you install the Django package. + +### Create the Django project + +1. In the VS Code Terminal where your virtual environment is activated, run the following command: + + ```bash + django-admin startproject web_project . + ``` + + This `startproject` command assumes (by use of `.` at the end) that the current folder is your project folder, and creates the following within it: + + - `manage.py`: The Django command-line administrative utility for the project. You run administrative commands for the project using `python manage.py [options]`. + + - A subfolder named `web_project`, which contains the following files: + - `__init__.py`: an empty file that tells Python that this folder is a Python package. + - `wsgi.py`: an entry point for WSGI-compatible web servers to serve your project. You typically leave this file as-is as it provides the hooks for production web servers. + - `settings.py`: contains settings for Django project, which you modify in the course of developing a web app. + - `urls.py`: contains a table of contents for the Django project, which you also modify in the course of development. + +1. To verify the Django project, make sure your virtual environment is activated, then start Django's development server using the command `python manage.py runserver`. The server runs on the default port 8000, and you see output like the following output in the terminal window: + + ```output + Performing system checks... + + System check identified no issues (0 silenced). + + September 05, 2018 - 14:33:31 + Django version 2.1.1, using settings 'web_project.settings' + Starting development server at http://127.0.0.1:8000/ + Quit the server with CTRL-BREAK. + ``` + + When you run the server the first time, it creates a default SQLite database in the file `db.sqlite3`, which is intended for development purposes but can be used in production for low-volume web apps. Also, Django's built-in web server is intended *only* for local development purposes. When you deploy to a web host, however, Django uses the host's web server instead. The `wsgi.py` module in the Django project takes care of hooking into the production servers. + + If you want to use a different port than the default 8000, specify the port number on the command line, such as `python manage.py runserver 5000`. + +1. `kbstyle(Ctrl+click)` the `http://127.0.0.1:8000/` URL in the terminal output window to open your default browser to that address. If Django is installed correctly and the project is valid, you see the default page shown below. The VS Code terminal output window also shows the server log. + + ![Django tutorial: default view of empty Django project](images/django-tutorial/django-empty-project-success.png) + +1. When you're done, close the browser window and stop the server in VS Code using `kbstyle(Ctrl+C)` as indicated in the terminal output window. + +### Create A Django app + +1. In the VS Code Terminal with your virtual environment activated, run the administrative utility's `startapp` command in your project folder (where `manage.py` resides): + + ```bash + python manage.py startapp hello + ``` + + The command creates a folder called `hello` that contains a number of code files and one subfolder. Of these, you frequently work with `views.py` (that contains the functions that define pages in your web app) and `models.py` (that contains classes defining your data objects). The `migrations` folder is used by Django's administrative utility to manage database versions as discussed later in this tutorial. There are also the files `apps.py` (app configuration), `admin.py` (for creating an administrative interface), and `tests.py` (for unit tests), which are not covered here. + +1. Modify `hello/views.py` to match the following code, which creates a single view for the app's home page: + + ```python + from django.http import HttpResponse + + def home(request): + return HttpResponse("Hello, Django!") + ``` + +1. Create a file, `hello/urls.py`, with the contents below. The `urls.py` file is where you specify patterns to route different URLs to their appropriate views. The code below contains one route to map root URL of the app (`""`) to the `view.home` function that you just added to `hello/views.py`: + + ```python + from django.urls import path + from hello import views + + urlpatterns = [ + path("", views.home, name="home"), + ] + ``` + +1. The `web_project` folder also contains a `urls.py` file, which is where URL routing is actually handled. Open `web_project/urls.py` and modify it to match the following code (you can retain the instructive comments if you like). This code pulls in the app's `hello/urls.py` using `django.urls.include`, which keeps the app's routes contained within the app. This separation is helpful when a project contains multiple apps. + + ```python + from django.contrib import admin + from django.urls import include, path + + urlpatterns = [ + path("", include("hello.urls")), + ] + ``` + +1. Save all modified files with `kb(workbench.action.files.saveAll)`. + +1. In the VS Code Terminal, again with the virtual environment activated, run the development server with `python manage.py runserver` and open a browser to `http://127.0.0.1:8000/` to see a page that renders "Hello, Django". + + ![Django tutorial: the basic Django app running in a browser](images/django-tutorial/app-in-browser-01.png) + +## Create a debugger launch profile + +You're probably already wondering if there's an easier way to run the server and test the app without typing `python manage.py runserver` each time. Fortunately, there is! You can create a customized launch profile in VS Code, which is also used for the inevitable exercise of debugging. + +1. Switch to **Debug** view in VS Code (using the left-side activity bar). Along the top of the Debug view, you may see "No Configurations" and a warning dot on the gear icon. Both indicators mean that you don't yet have a `launch.json` file containing debug configurations: + + ![Django tutorial: initial view of the debug panel](images/shared/debug-panel-initial-view.png) + +1. Select the gear icon and wait for a few seconds for VS Code to create and open a `launch.json` file. (If you're using an older version of VS Code, you may be prompted with a list of debugger targets, in which case select **Python** from the list.) The `launch.json` file contains a number of debugging configurations, each of which is a separate JSON object within the `configuration` array. + +1. Scroll down to and examine the configuration with the name "Python: Django": + + ```json + { + "name": "Python: Django", + "type": "python", + "request": "launch", + "program": "${workspaceFolder}/manage.py", + "console": "integratedTerminal", + "args": [ + "runserver", + "--noreload", + "--nothreading" + ], + "django": true + }, + ``` + + This configuration tells VS Code to run `"${workspaceFolder}/manage.py"` using the selected Python interpreter and the arguments in the `args` list. Launching the VS Code debugger with this configuration, then, is the same as running `python manage.py runserver --noreload --nothreading` in the VS Code Terminal with your activated virtual environment. (You can add a port number like `"5000"` to `args` if desired.) The `"django": true` entry also tells VS Code to enable debugging of Django page templates, which you see later in this tutorial. + + > **Note**: If you use Chrome as your debugging browser, remove `--nothreading` due to [Chromium issue 13043](https://code.google.com/p/chromium-os/issues/detail?id=13043). + +1. Save `launch.json` (`kb(workbench.action.files.save)`). In the debug configuration drop-down list (which reads **Python: Current File**) select the **Python: Django** configuration: + + ![Django tutorial: selecting the Django debugging configuration](images/django-tutorial/debug-select-configuration.png) + +1. Test the configuration by selecting the **Debug** > **Start Debugging** menu command, or selecting the green **Start Debugging** arrow next to the list (`kb(workbench.action.debug.continue)`): + + ![Django tutorial: start debugging/continue arrow on the debug toolbar](images/django-tutorial/debug-continue-arrow.png) + +1. `kbstyle(Ctrl+click)` the `http://127.0.0.1:8000/` URL in the terminal output window to open the browser and see that the app is running properly. + +1. Close the browser and stop the debugger when you're finished. To stop the debugger, use the Stop toolbar button (the red square) or the **Debug** > **Stop Debugging** command (`kb(workbench.action.debug.stop)`). + +1. You can now use the **Debug** > **Start Debugging** at any time to test the app, which also has the benefit of automatically saving all modified files. + +## Explore the debugger + +Debugging gives you the opportunity to pause a running program on a particular line of code. When a program is paused, you can examine variables, run code in the Debug Console panel, and otherwise take advantage of the features described on [Debugging](/docs/python/debugging.md). Running the debugger also automatically saves any modified files before the debugging session begins. + +**Before you begin**: Make sure you've stopped the running app at the end of the last section by using `kbstyle(Ctrl+C)` in the terminal. If you leave the app running in one terminal, it continues to own the port. As a result, when you run the app in the debugger using the same port, the original running app handles all the requests and you won't see any activity in the app being debugged and the program won't stop at breakpoints. In other words, if the debugger doesn't seem to be working, make sure that no other instance of the app is still running. + +1. In `hello/urls.py`, add a route to the `urlpatterns` list: + + ```python + path("hello/", views.hello_there, name="hello_there"), + ``` + + The first argument to `path` defines a route "hello/" that accepts a variable string called *name*. The string is passed to the `views.hello_there` function specified in the second argument to `path`. + + URL routes are case-sensitive. For example, the route `/hello/` is distinct from `/Hello/`. If you want the same view function to handle both, define paths for each variant. + +1. Replace the contents of `views.py` with the following code to define the `hello_there` function that you can step through in the debugger: + + ```python + import re + from datetime import datetime + from django.http import HttpResponse + + def home(request): + return HttpResponse("Hello, Django!") + + def hello_there(request, name): + now = datetime.now() + formatted_now = now.strftime("%A, %d %B, %Y at %X") + + # Filter the name argument to letters only using regular expressions. URL arguments + # can contain arbitrary text, so we restrict to safe characters only. + match_object = re.match("[a-zA-Z]+", name) + + if match_object: + clean_name = match_object.group(0) + else: + clean_name = "Friend" + + content = "Hello there, " + clean_name + "! It's " + formatted_now + return HttpResponse(content) + ``` + + The `name` variable defined in the URL route is given as an argument to the `hello_there` function. As described in the code comments, always filter arbitrary user-provided information to avoid various attacks on your app. In this case, the code filters the name argument to contain only letters, which avoids injection of control characters, HTML, and so forth. (When you use templates in the next section, Django does automatic filtering and you don't need this code.) + +1. Set a breakpoint at the first line of code in the `hello_there` function (`now = datetime.now()`) by doing any one of the following: + - With the cursor on that line, press `kb(editor.debug.action.toggleBreakpoint)`, or, + - With the cursor on that line, select the **Debug** > **Toggle Breakpoint** menu command, or, + - Click directly in the margin to the left of the line number (a faded red dot appears when hovering there). + + The breakpoint appears as a red dot in the left margin: + + ![Django tutorial: a breakpoint set on the first line of the hello_there function](images/django-tutorial/debug-breakpoint-set.png) + +1. Start the debugger by selecting the **Debug** > **Start Debugging** menu command, or selecting the green **Start Debugging** arrow next to the list (`kb(workbench.action.debug.continue)`): + + ![Django tutorial: start debugging/continue arrow on the debug toolbar](images/django-tutorial/debug-continue-arrow.png) + + Observe that the status bar changes color to indicate debugging: + + ![Django tutorial: appearance of the debugging status bar](images/django-tutorial/debug-status-bar.png) + + A debugging toolbar (shown below) also appears in VS Code containing commands in the following order: Pause (or Continue, `kb(workbench.action.debug.continue)`), Step Over (`kb(workbench.action.debug.stepOver)`), Step Into (`kb(workbench.action.debug.stepInto)`), Step Out (`kb(workbench.action.debug.stepOut)`), Restart (`kb(workbench.action.debug.restart)`), and Stop (`kb(workbench.action.debug.stop)`). See [VS Code debugging](/docs/editor/debugging.md) for a description of each command. + + ![Django tutorial: the VS Code debug toolbar](images/shared/debug-toolbar.png) + +1. Output appears in a "Python Debug Console" terminal. Open a browser and navigate to `http://127.0.0.1:8000/hello/VSCode`. Before the page renders, VS Code pauses the program at the breakpoint you set. The small yellow arrow on the breakpoint indicates that it's the next line of code to run. + + ![Django tutorial: VS Code paused at a breakpoint](images/django-tutorial/debug-program-paused.png) + +1. Use Step Over to run the `now = datetime.now()` statement. + +1. On the left side of the VS Code window, you see a **Variables** pane that shows local variables, such as `now`, as well as arguments, such as `name`. Below that are panes for **Watch**, **Call Stack**, and **Breakpoints** (see [VS Code debugging](/docs/editor/debugging.md) for details). In the **Locals** section, try expanding different values. You can also double-click values (or use `kb(debug.setVariable)`) to modify them. Changing variables such as `now`, however, can break the program. Developers typically make changes only to correct values when the code didn't produce the right value to begin with. + + ![Django tutorial: local variables and arguments in VS Code during debugging](images/django-tutorial/debug-local-variables.png) + +1. When a program is paused, the **Debug Console** panel (which is different from the "Python Debug Console" in the Terminal panel) lets you experiment with expressions and try out bits of code using the current state of the program. For example, once you've stepped over the line `now = datetime.now()`, you might experiment with different date/time formats. In the editor, select the code that reads `now.strftime("%A, %d %B, %Y at %X")`, then right-click and select **Debug: Evaluate** to send that code to the debug console, where it runs: + + ```bash + now.strftime("%A, %d %B, %Y at %X") + 'Friday, 07 September, 2018 at 07:46:32' + ``` + + > **Tip**: The **Debug Console** also shows exceptions from within the app that may not appear in the terminal. For example, if you see a "Paused on exception" message in the **Call Stack** area of Debug View, switch to the **Debug Console** to see the exception message. + +1. Copy that line into the > prompt at the bottom of the debug console, and try changing the formatting: + + ```bash + now.strftime("%a, %d %B, %Y at %X") + 'Fri, 07 September, 2018 at 07:46:32' + now.strftime("%a, %d %b, %Y at %X") + 'Fri, 07 Sep, 2018 at 07:46:32' + now.strftime("%a, %d %b, %y at %X") + 'Fri, 07 Sep, 18 at 07:46:32' + ``` + + > **Note**: If you see a change you like, you can copy and paste it into the editor during a debugging session. However, those changes aren't applied until you restart the debugger. + +1. Step through a few more lines of code, if you'd like, then select Continue (`kb(workbench.action.debug.continue)`) to let the program run. The browser window shows the result: + + ![Django tutorial: result of the modified program](images/django-tutorial/debug-run-result.png) + +1. Close the browser and stop the debugger when you're finished. To stop the debugger, use the Stop toolbar button (the red square) or the **Debug** > **Stop Debugging** command (`kb(workbench.action.debug.stop)`). + +> **Tip**: To make it easier to repeatedly navigate to a specific URL like `http://127.0.0.1:8000/hello/VSCode`, output that URL using a `print` statement somewhere in a file like `views.py`. The URL appears in the VS Code Terminal where you can use `kbstyle(Ctrl+click)` to open it in a browser. + +## Go to Definition and Peek Definition commands + +During your work with Django or any other library, you may want to examine the code in those libraries themselves. VS Code provides two convenient commands that navigate directly to the definitions of classes and other objects in any code: + +- **Go to Definition** jumps from your code into the code that defines an object. For example, in `views.py`, right-click on `HttpResponse` in the `home` function and select **Go to Definition** (or use `kb(editor.action.revealDefinition)`), which navigates to the class definition in the Django library. + +- **Peek Definition** (`kb(editor.action.peekDefinition)`, also on the right-click context menu), is similar, but displays the class definition directly in the editor (making space in the editor window to avoid obscuring any code). Press `kbstyle(Escape)` to close the Peek window or use the **x** in the upper right corner. + + ![Django tutorial: Peek Definition showing the Flask class inline](images/django-tutorial/peek-definition.png) + +## Use a template to render a page + +The app you've created so far in this tutorial generates only plain text web pages from Python code. Although it's possible to generate HTML directly in code, developers avoid such a practice because it opens the app to [cross-site scripting (XSS) attacks](https://en.wikipedia.org/wiki/Cross-site_scripting). In the `hello_there` function of this tutorial, for example, one might think to format the output in code with something like `content = "

Hello there, " + clean_name + "!

`, where the result in `content` is given directly to a browser. This opening allows an attacker to place malicious HTML, including JavaScript code, in the URL that ends up in `clean_name` and thus ends up being run in the browser. + +A much better practice is to keep HTML out of your code entirely by using **templates**, so that your code is concerned only with data values and not with rendering. + +In Django, a template is an HTML file that contains placeholders for values that the code provides at run time. The Django templating engine then takes care of making the substitutions when rendering the page, and provides automatic escaping to prevent XSS attacks (that is, if you tried using HTML in a data value, you would see the HTML rendered only as plain text). The code, therefore, concerns itself only with data values and the template concerns itself only with markup. Django templates provide flexible options such as template inheritance, which allows you to define a base page with common markup and then build upon that base with page-specific additions. + +In this section, you start by creating a single page using a template. In subsequent sections, you configure the app to serve static files and then create multiple pages to the app that each contains a nav bar from a base template. Django templates also support control flow and iteration, as you see later in this tutorial in the context of template debugging. + +1. In the `web_project/settings.py` file, locate the `INSTALLED_APPS` list and add the following entry, which makes sure the project knows about the app so it can handle templating: + + ```python + 'hello', + ``` + +1. Inside the `hello` folder, create a folder named `templates`, and then another subfolder named `hello` to match the app name (this two-tiered folder structure is typical Django convention). + +1. In the `templates/hello` folder, create a file named `hello_there.html` with the contents below. This template contains two placeholders for data values named "name", and "date", which are delineated by pairs of curly braces, `\{{` and `}}`. All other invariant text is part of the template, along with formatting markup (such as ``). As you can see, template placeholders can also include formatting, the expressions after the pipe `|` symbols, in this case using Django's built-in [date filter](https://docs.djangoproject.com/en/2.1/ref/templates/builtins/#date) and [time filter](https://docs.djangoproject.com/en/2.1/ref/templates/builtins/#time). The code, then needs only to pass the datetime *value* rather than a pre-formatted string: + + ```html + + + + + Hello, Django + + + Hello there, \{{ name }}! It's \{{ date | date:'l, d F, Y' }} at \{{ date | time:'H:i:s' }} + + + ``` + +1. At the top of `views.py`, add the following import statement: + + ```python + from django.shortcuts import render + ``` + +1. Also in `views.py`, modify the `hello_there` function to use `django.shortcuts.render` method to load a template and to provide the *template context*. The context is simply the set of variables for use within the template. The `render` function takes the request object, followed by the path to to the template *relative to the `templates` folder*, then the context object. (Developers typically name the templates the same as the functions that use them, but matching names are not required because you always refer to the exact filename in your code.) + + ```python + def hello_there(request, name): + return render( + request, + 'hello/hello_there.html', + { + 'name': name, + 'date': datetime.now() + } + ) + ``` + + You can see that the code is now much simpler, and concerned only with data values, because the markup and formatting is all contained in the template. + +1. Start the program (inside or outside of the debugger, using `kb(workbench.action.debug.run)`), navigate to a /hello/name URL, and observe the results. + +1. Also try navigating to a /hello/name URL using a name like `` to see Django's automatic escaping at work. The "name" value shows up as plain text in the browser rather than as rendering an actual element. + +## Serve static files + +Static files are pieces of content that your web app returns as-is for certain requests, such as CSS files. Serving static files requires that the `INSTALLED_APPS` list in `settings.py` contains `django.contrib.staticfiles`, which is included by default. + +Serving static files in Django is something of an art, especially when deploying to production. What's shown here is a simple approach that works with the Django development server and also a production server like gunicorn. A full treatment of static files, however, is beyond the scope of this tutorial, so for more information, see [Managing static files](https://docs.djangoproject.com/en/2.1/howto/static-files/) in the Django documentation. + +In production, you also need to set `DEBUG=False` in `settings.py`, which necessitates some additional work when using containers. For details, see [Issue 13](https://github.com/Microsoft/python-sample-vscode-django-tutorial/issues/13). + +### Ready the app for static files + +1. In the project's `web_project/urls.py`, add the following `import` statement: + + ```python + from django.contrib.staticfiles.urls import staticfiles_urlpatterns + ``` + +1. In that same file, add the following line at the end, which includes standard static file URLs to the list that the project recognizes: + + ```python + urlpatterns += staticfiles_urlpatterns() + ``` + +### Refer to static files in a template + +1. In the `hello` folder, create a folder named `static`. + +1. Within the `static` folder, create a subfolder named `hello`, matching the app name. + + The reason for this extra subfolder is that when you deploy the Django project to a production server, you collect all the static files into a single folder that's then served by a dedicated static file server. The `static/hello` subfolder ensures that when the app's static files are collected, they're in an app-specific subfolder and won't collide with file from other apps in the same project. + +1. In the `static/hello` folder, create a file named `site.css` with the following contents. After entering this code, also observe the syntax highlighting that VS Code provides for CSS files, including a color preview. + + ```css + .message { + font-weight: 600; + color: blue; + } + ``` + +1. In `templates/hello/hello_there.html`, add the following lines after the `` element. The `{% load static %}` tag is a custom Django template tag set, which allows you to use `{% static %}` to refer to a file like the stylesheet. + + ```html + {% load static %} + <link rel="stylesheet" type="text/css" href="{% static 'hello/site.css' %}" /> + ``` + +1. Also in `templates/hello/hello_there.html`, replace the contents `<body>` element with the following markup that uses the `message` style instead of a `<strong>` tag: + + ```html + <span class="message">Hello, there \{{ name }}!</span> It's \{{ date | date:'l, d F, Y' }} at \{{ date | time:'H:i:s' }}. + ``` + +1. Run the app, navigate to a /hello/name URL, and observe that the message renders in blue. Stop the app when you're done. + +### Use the collectstatic command + +For production deployments, you typically collect all the static files from your apps into a single folder using the `python manage.py collectstatic` command. You can then use a dedicated static file server to serve those files, which typically results in better overall performance. The following steps show how this collection is made, although you don't use the collection when running with the Django development server. + +1. In `web_project/settings.py`, add the following line that defines a location where static files are collected when you use the `collectstatic` command: + + ```python + STATIC_ROOT = os.path.join(BASE_DIR, 'static_collected') + ``` + +1. In the Terminal, run the command `python manage.py collectstatic` and observe that `hello/site.css` is copied into the top level `static_collected` folder alongside `manage.py`. + +1. In practice, run `collectstatic` any time you change static files and before deploying into production. + +## Create multiple templates that extend a base template + +Because most web apps have more than one page, and because those pages typically share many common elements, developers separate those common elements into a base page template that other page templates then extend. (This is also called template inheritance, meaning the extended pages inherit elements from the base page.) + +Also, because you'll likely create many pages that extend the same template, it's helpful to create a code snippet in VS Code with which you can quickly initialize new page templates. A snippet helps you avoid tedious and error-prone copy-paste operations. + +The following sections walk through different parts of this process. + +### Create a base page template and styles + +A base page template in Django contains all the shared parts of a set of pages, including references to CSS files, script files, and so forth. Base templates also define one or more **block** tags with content that extended templates are expected to override. A block tag is delineated by `{% block <name> %}` and `{% endblock %}` in both the base template and extended templates. + +The following steps demonstrate creating a base template. + +1. In the `templates/hello` folder, create a file named `layout.html` with the contents below, which contains blocks named "title" and "content". As you can see, the markup defines a simple nav bar structure with links to Home, About, and Contact pages, which you create in a later section. Notice the use of Django's `{% url %}` tag to refer to other pages through the names of the corresponding URL patterns rather than by relative path. + + ```html + <!DOCTYPE html> + <html> + <head> + <meta charset="utf-8"/> + <title>{% block title %}{% endblock %} + {% load static %} + + + + +
+ Home + About + Contact +
+ +
+ {% block content %} + {% endblock %} +
+
+

© 2018

+
+
+ + + ``` + +1. Add the following styles to `static/hello/site.css` below the existing "message" style, and save the file. (This walkthrough doesn't attempt to demonstrate responsive design; these styles simply generate a reasonably interesting result.) + + ```css + .navbar { + background-color: lightslategray; + font-size: 1em; + font-family: 'Trebuchet MS', 'Lucida Sans Unicode', 'Lucida Grande', 'Lucida Sans', Arial, sans-serif; + color: white; + padding: 8px 5px 8px 5px; + } + + .navbar a { + text-decoration: none; + color: inherit; + } + + .navbar-brand { + font-size: 1.2em; + font-weight: 600; + } + + .navbar-item { + font-variant: small-caps; + margin-left: 30px; + } + + .body-content { + padding: 5px; + font-family:'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; + } + ``` + +You can run the app at this point, but because you haven't made use of the base template anywhere and haven't changed any code files, the result is the same as the previous step. Complete the remaining sections to see the final effect. + +### Create a code snippet + +Because the three pages you create in the next section extend `layout.html`, it saves time to create a **code snippet** to initialize a new template file with the appropriate reference to the base template. A code snippet provides a consistent piece of code from a single source, which avoids errors that can creep in when using copy-paste from existing code. + +1. In VS Code, select the **File** (Windows/Linux) or **Code** (macOS), menu, then select **Preferences** > **User snippets**. + +1. In the list that appears, select **html**. (The option may appear as "html.json" in the **Existing Snippets** section of the list if you've created snippets previously.) + +1. After VS code opens `html.json`, add the code below within the existing curly braces. (The explanatory comments, not shown here, describe details such as how the `$0` line indicates where VS Code places the cursor after inserting a snippet): + + ```json + "Django Tutorial: template extending layout.html": { + "prefix": "djextlayout", + "body": [ + "{% extends \"hello/layout.html\" %}", + "{% block title %}", + "$0", + "{% endblock %}", + "{% block content %}", + "{% endblock %}" + ], + + "description": "Boilerplate template that extends layout.html" + }, + ``` + +1. Save the `html.json` file (`kb(workbench.action.files.save)`). + +1. Now, whenever you start typing the snippet's prefix, such as `djext`, VS Code provides the snippet as an autocomplete option, as shown in the next section. You can also use the **Insert Snippet** command to choose a snippet from a menu. + +For more information on code snippets in general, refer to [Creating snippets](/docs/editor/userdefinedsnippets.md). + +### Use the code snippet to add pages + +With the code snippet in place, you can quickly create templates for the Home, About, and Contact pages. + +1. In the `templates/hello` folder, create a new file named `home.html`, Then start typing `djext` to see the snippet appear as a completion: + + ![Django tutorial: autocompletion for the djextlayout code snippet](images/django-tutorial/autocomplete-for-code-snippet.png) + + When you select the completion, the snippet's code appears with the cursor on the snippet's insertion point: + + ![Django tutorial: insertion of the djextlayout code snippet](images/django-tutorial/code-snippet-inserted.png) + +1. At the insertion point in the "title" block, write `Home`, and in the "content" block, write `

Home page for the Visual Studio Code Django tutorial.

`, then save the file. These lines are the only unique parts of the extended page template: + +1. In the `templates/hello` folder, create `about.html`, use the snippet to insert the boilerplate markup, insert `About us` and `

About page for the Visual Studio Code Django tutorial.

` in the "title" and "content" blocks, respectively, then save the file. + +1. Repeat the previous step to create `templates/hello/contact.html` using `Contact us` and `

Contact page for the Visual Studio Code Django tutorial.

`. + +1. In the app's `urls.py`, add routes for the /about and /contact pages. Be mindful that the `name` argument to the `path` function defines the name with which you refer to the page in the `{% url %}` tags in the templates. + + ```python + path("about/", views.about, name="about"), + path("contact/", views.contact, name="contact"), + ``` + +1. In `views.py`, add functions for the /about and /contact routes that refer to their respective page templates. Also modify the `home` function to use the `home.html` template. + + ```python + # Replace the existing home function with the one below + def home(request): + return render(request, "hello/home.html") + + def about(request): + return render(request, "hello/about.html") + + def contact(request): + return render(request, "hello/contact.html") + ``` + +### Run the app + +With all the page templates in place, save `views.py`, run the app, and open a browser to the home page to see the results. Navigate between the pages to verify that the page templates are properly extending the base template. + +![Django tutorial: app rendering a common nav bar from the base template](images/django-tutorial/full-app.png) + +## Work with data, data models, and migrations + +Many web apps work with information stored in a database, and Django makes it easy to represent the objects in that database using *models*. In Django, a model is a Python class, derived from `django.db.models.Model`, that represents a specific database object, typically a table. You place these classes in an app's `models.py` file. + +With Django, your work with your database almost exclusively through the models you define in code. Django's "migrations" then handle all the details of the underlying database automatically as you evolve the models over time. The general workflow is as follows: + +1. Make changes to the models in your *models.py* file. +1. Run `python manage.py makemigrations` to generate scripts in the `migrations` folder that migrate the database from its current state to the new state. +1. Run `python manage.py migrate` to apply the scripts to the actual database. + +The migration scripts effectively record all the incremental changes you make to your data models over time. By applying the migrations, Django updates the database to match your models. Because each incremental change has its own script, Django can automatically migrate *any* previous version of a database (including a new database) to the current version. As a result, you need concern yourself only with your models in `models.py`, never with the underlying database schema or the migration scripts. You let Django do that part! + +In code, too, you work exclusively with your model classes to store and retrieve data; Django handles the underlying details. The one exception is that you can write data into your database using the Django administrative utility [loaddata command](https://docs.djangoproject.com/en/2.1/ref/django-admin/#loaddata). This utility is often used to initialize a data set after the `migrate` command has initialized the schema. + +When using the `db.sqlite3` file, you can also work directly with the database using a tool like the [SQLite browser](http://sqlitebrowser.org/). It's fine to add or delete records in tables using such a tool, but avoid making changes to the database schema because the database will then be out of sync with your app's models. Instead, change the models, run `makemigrations`, then run `migrate`. + +### Types of databases + +By default, Django includes a `db.sqlite3` file for an app's database that's suitable for development work. As described on [When to use SQLite](https://www.sqlite.org/whentouse.html) (sqlite.org), SQLite works fine for low to medium traffic sites with fewer than 100 K hits/day, but is not recommended for higher volumes. It's also limited to a single computer, so it cannot be used in any multi-server scenario such as load-balancing and geo-replication. + +For these reasons, consider using a production-level data store such as [PostgreSQL](https://www.postgresql.org/), [MySQL](https://www.mysql.com/), and [SQL Server](https://www.microsoft.com/en-ca/sql-server/). For information on Django's support for other databases, see [Database setup](https://docs.djangoproject.com/en/2.1/intro/tutorial02/#database-setup). You can also use the [Azure SDK for Python](https://docs.microsoft.com/visualstudio/python/azure-sdk-for-python) to work with Azure storage services like tables and blobs. + +### Define models + +A Django model is again a Python class derived from `django.db.model.Models`, which you place in the app's `models.py` file. In the database, each model is automatically given a unique ID field named `id`. All other fields are defined as properties of the class using types from `django.db.models` such as `CharField` (limited text), `TextField` (unlimited text), `EmailField`, `URLField`, `IntegerField`, `DecimalField`, `BooleanField`. `DateTimeField`, `ForeignKey`, and `ManyToMany`, among others. (See the [Model field reference](https://docs.djangoproject.com/en/2.1/ref/models/fields/) in the Django documentation for details.) + +Each field takes some attributes, like `max_length`. The `blank=True` attribute means the field is optional; `null=true` means that a value is optional. There is also a `choices` attribute that limits values to values in an array of data value/display value tuples. + +For example, add the following class in `models.py` to define a data model that represents dated entries in a simple message log: + +```python +from django.db import models +from django.utils import timezone + +class LogMessage(models.Model): + message = models.CharField(max_length=300) + log_date = models.DateTimeField("date logged") + + def __str__(self): + """Returns a string representation of a message.""" + date = timezone.localtime(self.log_date) + return f"'{self.message}' logged on {date.strftime('%A, %d %B, %Y at %X')}" +``` + +A model class can include methods that return values computed from other class properties. Models typically include a `__str__` method that returns a string representation of the instance. + +### Migrate the database + +Because you changed your data models by editing `models.py`, you need to update the database itself. In VS Code, open a Terminal with your virtual environment activated (use the **Terminal: Create New Integrated Terminal** command, `kb(workbench.action.terminal.new)`)), navigate to the project folder, and run the following commands: + +```bash +python manage.py makemigrations +python manage.py migrate +``` + +Take a look in the `migrations` folder to see the scripts that `makemigrations` generates. You can also look at the database itself to see that the schema is updated. + +If you see errors when running the commands, make sure you're not using a debugging terminal that's left over from previous steps, as they may not have the virtual environment activated. + +### Use the database through the models + +With your models in place and the database migrated, you can store and retrieve data using only your models. In this section, you add a form page to the app through which you can log a message. You then modify the home page to display those messages. Because you modify many code files here, be mindful of the details. + +1. In the `hello` folder (where you have `views.py`), create a new file named `forms.py` with the following code, which defines a Django form that contains field drawn from the data model, `LogMessage`: + + ```python + from django import forms + from hello.models import LogMessage + + class LogMessageForm(forms.ModelForm): + class Meta: + model = LogMessage + fields = ("message",) # NOTE: the trailing comma is required + ``` + +1. In the `templates/hello` folder, create a new template named `log_message.html` with the following contents, which assumes that the template is given a variable named `form` to define the body of the form. It then adds a submit button with the label "Log". + + ```html + {% extends "hello/layout.html" %} + {% block title %} + Log a message + {% endblock %} + {% block content %} +
+ {% csrf_token %} + \{{ form.as_p }} + +
+ {% endblock %} + ``` + + > **Note**: Django's `{% csrf_token %}` tag provides protection from cross-site request forgeries. See [Cross Site Request Forgery protection](https://docs.djangoproject.com/en/2.1/ref/csrf/) in the Django documentation for details. + +1. In the app's `static/hello/site.css` file, add a rule to make the input form wider: + + ```css + input[name=message] { + width: 80%; + } + ``` + +1. In the app's `urls.py` file, add a route for the new page: + + ```python + path("log/", views.log_message, name="log"), + ``` + +1. In `views.py`, define the view named `log_message` (as referred to by the URL route). This view handles both HTTP GET and POST cases. In the GET case (the `else:` section), it just displays the form that you defined in the previous steps. In the POST case, it retrieves the data from the form into a data object (`message`), sets the timestamp, then saves that object at which point it's written to the database: + + ```python + # Add these to existing imports at the top of the file: + from django.shortcuts import redirect + from hello.forms import LogMessageForm + from hello.models import LogMessage + + # Add this code elsewhere in the file: + def log_message(request): + form = LogMessageForm(request.POST or None) + + if request.method == "POST": + if form.is_valid(): + message = form.save(commit=False) + message.log_date = datetime.now() + message.save() + return redirect("home") + else: + return render(request, "hello/log_message.html", {"form": form}) + ``` + +1. One more step before you're ready to try everything out! In `templates/hello/layout.html`, add a link in the "navbar" div for the message logging page: + + ```html + + Log Message + ``` + +1. Run the app and open a browser to the home page. Select the **Log Message** link on the nav bar, which should display the message logging page: + + ![Django tutorial: the message logging page added to the app](images/django-tutorial/message-logging-page.png) + +1. Enter a message, select **Log**, and you should be taken back to the home page. The home page doesn't yet show any of the logged messages yet (which you remedy in a moment). Feel free to log a few more messages as well. If you want, peek in the database using a tool like SQLite Browser to see that records have been created. Open the database as read-only, or otherwise remember to close the database before using the app, otherwise the app will fail because the database is locked. + +1. Stop the app when you're done. + +1. Now modify the home page to display the logged messages. Start by replacing the contents of app's `templates/hello/home.html` file with the markup below. This template expects a context variable named `message_list`. If it receives one (checked with the `{% if message_list %}` tag), it then iterates over that list (the `{% for message in message_list %}` tag) to generate table rows for each message. Otherwise the page indicates that no messages have yet been logged. + + ```html + {% extends "hello/layout.html" %} + {% block title %} + Home + {% endblock %} + {% block content %} +

Logged messages

+ + {% if message_list %} + + + + + + + + + + {% for message in message_list %} + + + + + + {% endfor %} + +
DateTimeMessage
\{{ message.log_date | date:'d M Y' }}\{{ message.log_date | time:'H:i:s' }} + \{{ message.message }} +
+ {% else %} +

No messages have been logged. Use the Log Message form.

+ {% endif %} + {% endblock %} + ``` + +1. In `static/hello/site.css`, add a rule to format the table a little: + + ```css + .message_list th,td { + text-align: left; + padding-right: 15px; + } + ``` + +1. In `views.py`, import Django's generic `ListView` class, which we'll use to implement the home page: + + ```python + from django.views.generic import ListView + ``` + +1. Also in `views.py`, replace the `home` function with a *class* named `HomeListView`, derived from `ListView`, which ties itself to the `LogMessage` model and implements a function `get_context_data` to generate the context for the template. + + ```python + # Remove the old home function if you want; it's no longer used + + class HomeListView(ListView): + """Renders the home page, with a list of all messages.""" + model = LogMessage + + def get_context_data(self, **kwargs): + context = super(HomeListView, self).get_context_data(**kwargs) + return context + ``` + +1. In the app's `urls.py`, import the data model: + + ```python + from hello.models import LogMessage + ``` + +1. Also in `urls.py`, make a variable for the new view, which retrieves the five most recent `LogMessage` objects in descending order (meaning that it queries the database), and then provides a name for the data in the template context (`message_list`), and identifies the template to use: + + ```python + home_list_view = views.HomeListView.as_view( + queryset=LogMessage.objects.order_by("-log_date")[:5], # :5 limits the results to the five most recent + context_object_name="message_list", + template_name="hello/home.html", + ) + ``` + +1. In `urls.py`, modify the path to the home page to use the `home_list_view` variable: + + ```python + # Replace the existing path for "" + path("", home_list_view, name="home"), + ``` + +1. Start the app and open a browser to the home page, which should now display messages: + + ![Django tutorial: app home page displaying message from the database](images/django-tutorial/app-with-message-list.png) + +1. Stop the app when you're done. + +## Use the debugger with page templates + +As shown in the previous section, page templates can contain procedural directives like `{% for message in message_list %}` and `{% if message_list %}`, rather than only passive, declarative elements like `{% url %}` and `{% block %}`. As a result, you can have programming errors inside templates as with any other procedural code. + +Fortunately, the Python Extension for VS Code provides template debugging when you have `"django": true` in the debugging configuration (as you do already). The following steps demonstrate this capability: + +1. In `templates/hello/home.html`, set breakpoints on both the `{% if message_list %}` and `{% for message in message_list %}` lines, as indicated by the yellow arrows in the image below: + + ![Django tutorial: breakpoints set in a Django page template](images/django-tutorial/template-breakpoints.png) + +1. Run the app in the debugger and open a browser to the home page. (If you're already running the debugger, you don't have to restart the app after setting breakpoints; just refresh the page.) Observe that VS Code breaks into the debugger in the template on the `{% if %}` statement and shows all the context variables in the **Variables** pane: + + ![Django tutorial: debugger stopped at breakpoints in the page template](images/django-tutorial/template-debugger.png) + +1. Use the Step Over (`kb(workbench.action.debug.stepOver)`) command to step through the template code. Observe that the debugger steps over all declarative statements and pauses at any procedural code. For example, stepping through the `{% for message in message_list %}` loops lets you examine each value in `message` and lets you step to lines like `\{{ message.log_date | date:'d M Y' }}`. + +1. You can also work with variables in the **Debug Console** panel. (Django filters like `date`, however, are not presently available in the console.) + +1. When you're ready, select Continue (`kb(workbench.action.debug.continue)`) to finish running the app and view the rendered page in the browser. Stop the debugger when you're done. + +## Optional activities + +The following sections describe additional steps that you might find helpful in your work with Python and Visual Studio Code. + +### Create a requirements.txt file for the environment + +When you share your app code through source control or some other means, it doesn't make sense to copy all the files in a virtual environment because recipients can always recreate that environment themselves. + +Accordingly, developers typically omit the virtual environment folder from source control and instead describe the app's dependencies using a `requirements.txt` file. + +Although you can create the file by hand, you can also use the `pip freeze` command to generate the file based on the exact libraries installed in the activated environment: + +1. With your chosen environment selected using the **Python: Select Interpreter** command, run the **Terminal: Create New Integrated Terminal** command (`kb(workbench.action.terminal.new)`)) to open a terminal with that environment activated. + +1. In the terminal, run `pip freeze > requirements.txt` to create the `requirements.txt` file in your project folder. + +Anyone (or any build server) that receives a copy of the project needs only to run the `pip install -r requirements.txt` command to reinstall the packages on which the app depends within the active environment. + +> **Note**: `pip freeze` lists all the Python packages you have installed in the current environment, including packages you aren't currently using. The command also lists packages with exact version numbers, which you might want to convert to ranges for more flexibility in the future. For more information, see [Requirements files](https://pip.readthedocs.io/1.1/requirements.html) in the pip command documentation. + +### Create a superuser and enable the administrative interface + +By default, Django provides an administrative interface for a web app that's protected by authentication. The interface is implemented through the build-in `django.contrib.admin` app, which is included by default in the project's `INSTALLED_APPS` list (`settings.py`), and authentication is handled with the built-in `django.contrib.auth` app, which is also in `INSTALLED_APPS` by default. + +Perform the following steps to enable the administrative interface: + +1. Create a superuser account in the app by opening a Terminal in VS Code for your virtual environment, then running the command `python manage.py createsuperuser --username= --email=`, replacing `` and ``, of course, with your personal information. When you run the command, Django prompts you to enter and confirm your password. + + Be sure to remember your username and password combination. These are the credentials you use to authenticate with the app. + +1. Add the following URL route in the project-level `urls.py` (`web_project/urls.py` in this tutorial) to point to the built-in administrative interface: + + ```python + # This path is included by default when creating the app + path("admin/", admin.site.urls), + ``` + +1. Run the server, the open a browser to the app's /admin page (such as `http://127.0.0.1:8000/admin` when using the development server). + +1. A login page appears, courtesy of `django.contrib.auth`. Enter your superuser credentials. + + ![Django tutorial: default Django login prompt](images/django-tutorial/login-prompt.png) + +1. Once you're authenticated, you see the default administration page, through which you can manage users and groups: + + ![Django tutorial: the default Django administrative interface](images/django-tutorial/default-admin-interface.png) + +You can customize the administrative interface as much as you like. For example, you could provide capabilities to edit and remove entries in the database. For more information on making customizations, refer to the [Django admin site documentation](https://docs.djangoproject.com/en/2.1/ref/contrib/admin/). + +## Next steps + +Congratulations on completing this walkthrough of working with Django in Visual Studio Code! + +The completed code project from this tutorial can be found on GitHub: [python-sample-vscode-django-tutorial](https://github.com/Microsoft/python-sample-vscode-django-tutorial). + +In this tutorial, we've only scratched the surface of everything Django can do. Be sure to visit the [Django documentation](https://docs.djangoproject.com/en/2.1/) and the [official Django tutorial](https://docs.djangoproject.com/en/2.1/intro/tutorial01/) for many more details on views, templates, data models, URL routing, the administrative interface, using other kinds of databases, deployment to production, and more. + +To try your app on a production website, check out the tutorial [Deploy Python apps to Azure App Service using Docker Containers](/docs/python/tutorial-deploy-containers.md). Azure also offers a standard container, [App Service on Linux (Preview)](/docs/python/tutorial-deploy-app-service-on-linux.md), to which you deploy web apps from within VS Code. + +You may also want to review the following articles in the VS Code docs that are relevant to Python: + +- [Editing Python code](/docs/python/editing.md) +- [Linting](/docs/python/linting.md) +- [Managing Python environments](/docs/python/environments.md) +- [Debugging Python](/docs/python/debugging.md) +- [Unit testing](/docs/python/unit-testing.md) + +If you encountered any problems in the course of this tutorial, feel free to file an issue in the [VS Code documentation repository](https://github.com/Microsoft/vscode-docs/issues). diff --git a/docs/python/tutorial-flask.md b/docs/python/tutorial-flask.md new file mode 100644 index 0000000000000000000000000000000000000000..500d0bd164055dce8769d71317288d9aea08a14b --- /dev/null +++ b/docs/python/tutorial-flask.md @@ -0,0 +1,684 @@ +--- +Order: 9 +Area: python +TOCTitle: Flask Tutorial +ContentId: 593d2dd6-20f0-4ad3-8ecd-067cc47ee217 +PageTitle: Python and Flask Tutorial in Visual Studio Code +DateApproved: 03/07/2019 +MetaDescription: Python Flask tutorial showing IntelliSense, debugging, and code navigation support in Visual Studio Code, the best Python IDE. +MetaSocialImage: images/tutorial/social.png +--- +# Flask Tutorial in Visual Studio Code + +[Flask](http://flask.pocoo.org/) is a lightweight Python framework for web applications that provides the basics for URL routing and page rendering. + +Flask is called a "micro" framework because it doesn't directly provide features like form validation, database abstraction, authentication, and so on. Such features are instead provided by special Python packages called Flask [extensions](http://flask.pocoo.org/extensions/). The extensions integrate seamlessly with Flask so that they appear as if they were part of Flask itself. For example, Flask doesn't provide a page template engine, but installing Flask includes the [Jinja](http://jinja.pocoo.org/) templating engine by default. For convenience, we typically speak of these defaults as part of Flask. + +In this Flask tutorial, you create a simple Flask app with three pages that use a common base template. Along the way, you experience a number of features of Visual Studio Code including using the terminal, the editor, the debugger, code snippets, and more. + +The completed code project for this Flask tutorial can be found on GitHub: [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial). + +If you have any problems, feel free to file an issue for this tutorial in the [VS Code documentation repository](https://github.com/Microsoft/vscode-docs/issues). + +## Prerequisites + +To successfully complete this Flask tutorial, you must do the following (which are the same steps as in the [general Python tutorial](/docs/python/python-tutorial.md)): + +1. Install the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python). + +1. Install a version of Python 3 (for which this tutorial is written). Options include: + - (All operating systems) A download from [python.org](https://www.python.org/downloads/); typically use the **Download Python 3.6.5** button that appears first on the page (or whatever is the latest version). + - (Linux) The built-in Python 3 installation works well, but to install other Python packages you must run `sudo apt install python3-pip` in the terminal. + - (macOS) An installation through [Homebrew](https://brew.sh/) on macOS using `brew install python3` (the system install of Python on macOS is not supported). + - (All operating systems) A download from [Anaconda](https://www.anaconda.com/download/) (for data science purposes). + +1. On Windows, make sure the location of your Python interpreter is included in your PATH environment variable. You can check the location by running `path` at the command prompt. If the Python interpreter's folder isn't included, open Windows Settings, search for "environment", select **Edit environment variables for your account**, then edit the **Path** variable to include that folder. + +## Create a project environment for the Flask tutorial + +In this section, you create a virtual environment in which Flask is installed. Using a virtual environment avoids installing Flask into a global Python environment and gives you exact control over the libraries used in an application. A virtual environment also makes it easy to [Create a requirements.txt file for the environment](#create-a-requirementstxt-file-for-the-environment). + +1. On your file system, create a project folder for this tutorial, such as `hello_flask`. + +1. In that folder, use the following command (as appropriate to your computer) to create a virtual environment named `env` based on your current interpreter: + + ```bash + # macOS/Linux + sudo apt-get install python3-venv # If needed + python3 -m venv env + + # Windows + python -m venv env + ``` + + > **Note**: Use a stock Python installation when running the above commands. If you use `python.exe` from an Anaconda installation, you see an error because the ensurepip module isn't available, and the environment is left in an unfinished state. + +1. Open the project folder in VS Code by running `code .`, or by running VS Code and using the **File** > **Open Folder** command. + +1. In VS Code, open the Command Palette (**View** > **Command Palette** or (`kb(workbench.action.showCommands)`)). Then select the **Python: Select Interpreter** command: + + ![Flask tutorial: opening the Command Palette in VS Code](images/shared/command-palette.png) + +1. The command presents a list of available interpreters that VS Code can locate automatically (your list will vary; if you don't see the desired interpreter, see [Configuring Python environments](/docs/python/environments.md)). From the list, select the virtual environment in your project folder that starts with `./env` or `.\env`: + + ![Flask tutorial: selecting the virtual environment for Python](images/shared/select-virtual-environment.png) + +1. Run **Terminal: Create New Integrated Terminal** (`kb(workbench.action.terminal.new)`)) from the Command Palette, which creates a terminal and automatically activates the virtual environment by running its activation script. + + > **Note**: On Windows, if your default terminal type is PowerShell, you may see an error that it cannot run activate.ps1 because running scripts is disabled on the system. The error provides a link for information on how to allow scripts. Otherwise, use **Terminal: Select Default Shell** to set "Command Prompt" or "Git Bash" as your default instead. + +1. The selected environment appears on the left side of the VS Code status bar, and notice the "(venv)" indicator that tells you that you're using a virtual environment: + + ![Flask tutorial: selected environment showing in the VS Code status bar](images/shared/environment-in-status-bar.png) + +1. Install Flask in the virtual environment by running one of the following commands in the VS Code Terminal: + + ```bash + # macOS/Linux + pip3 install flask + + # Windows + pip install flask + ``` + +You now have a self-contained environment ready for writing Flask code. VS Code activates the environment automatically when you use **Terminal: Create New Integrated Terminal**. If you open a separate command prompt or terminal, activate the environment by running `source env/bin/activate` (Linux/macOS) or `env\scripts\activate` (Windows). You know the environment is activated when the command prompt shows **(env)** at the beginning. + +## Create and run a minimal Flask app + +1. In VS Code, create a new file in your project folder named `app.py` using either **File** > **New** from the menu, pressing `kbstyle(Ctrl+N)`, or using the new file icon in the Explorer View (shown below). + + ![Flask tutorial: new file icon in Explorer View](images/flask-tutorial/new-file-icon.png) + +1. In `app.py`, add code to import Flask and create an instance of the Flask object. If you type the code below (instead of using copy-paste), you can observe VS Code's [IntelliSense and auto-completions](/docs/python/editing.md#autocomplete-and-intellisense): + + ```python + from flask import Flask + app = Flask(__name__) + ``` + +1. Also in `app.py`, add a function that returns content, in this case a simple string, and use Flask's `app.route` decorator to map the URL route `/` to that function: + + ```python + @app.route("/") + def home(): + return "Hello, Flask!" + ``` + + > **Tip**: You can use multiple decorators on the same function, one per line, depending on how many different routes you want to map to the same function. + +1. Save the `app.py` file (`kb(workbench.action.files.save)`). + +1. In the terminal, run the app by entering `python3 -m flask run` (macOS/Linux) or `python -m flask run` (Windows), which runs the Flask development server. The development server looks for `app.py` by default. When you run Flask, you should see output similar to the following: + + ```bash + (env) D:\py\\hello_flask>python -m flask run + * Environment: production + WARNING: Do not use the development server in a production environment. + Use a production WSGI server instead. + * Debug mode: off + * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) + ``` + + If you see an error that the Flask module cannot be found, make sure you've run `pip3 install flask` (macOS/Linux) or `pip install flask` (Windows) in your virtual environment as described at the end of the previous section. + + Also, if you want to run the development server on a different IP address or port, use the host and port command-line arguments, as with `--host=0.0.0.0 --port=80`. + +1. To open your default browser to the rendered page, `kbstyle(Ctrl+click)` the `http://127.0.0.1:5000/` URL in the terminal. + + ![Flask tutorial: the running app in a browser](images/flask-tutorial/app-in-browser-01.png) + +1. Observe that when you visit a URL like /, a message appears in the debug terminal showing the HTTP request: + + ```bash + 127.0.0.1 - - [11/Jul/2018 08:40:15] "GET / HTTP/1.1" 200 - + ``` + +1. Stop the app by using `kbstyle(Ctrl+C)` in the terminal. + +> **Tip**: If you want to use a different filename than `app.py`, such as `program.py`, define an environment variable named FLASK_APP and set its value to your chosen file. Flask's development server then uses the value of FLASK_APP instead of the default file `app.py`. For more information, see [Flask command line interface](http://flask.pocoo.org/docs/1.0/cli/). + +## Run the app in the debugger + +Debugging gives you the opportunity to pause a running program on a particular line of code. When a program is paused, you can examine variables, run code in the Debug Console panel, and otherwise take advantage of the features described on [Debugging](/docs/python/debugging.md). Running the debugger also automatically saves any modified files before the debugging session begins. + +**Before you begin**: Make sure you've stopped the running app at the end of the last section by using `kbstyle(Ctrl+C)` in the terminal. If you leave the app running in one terminal, it continues to own the port. As a result, when you run the app in the debugger using the same port, the original running app handles all the requests and you won't see any activity in the app being debugged and the program won't stop at breakpoints. In other words, if the debugger doesn't seem to be working, make sure that no other instance of the app is still running. + +1. Replace the contents of `app.py` with the following code, which adds a second route and function that you can step through in the debugger: + + ```python + from flask import Flask + from datetime import datetime + import re + + app = Flask(__name__) + + @app.route("/") + def home(): + return "Hello, Flask!" + + @app.route("/hello/") + def hello_there(name): + now = datetime.now() + formatted_now = now.strftime("%A, %d %B, %Y at %X") + + # Filter the name argument to letters only using regular expressions. URL arguments + # can contain arbitrary text, so we restrict to safe characters only. + match_object = re.match("[a-zA-Z]+", name) + + if match_object: + clean_name = match_object.group(0) + else: + clean_name = "Friend" + + content = "Hello there, " + clean_name + "! It's " + formatted_now + return content + ``` + + The decorator used for the new URL route, `/hello/`, defines an endpoint /hello/ that can accept any additional value. The identifier inside `<` and `>` in the route defines a variable that is passed to the function and can be used in your code. + + URL routes are case-sensitive. For example, the route `/hello/` is distinct from `/Hello/`. If you want the same function to handle both, use decorators for each variant. + + As described in the code comments, always filter arbitrary user-provided information to avoid various attacks on your app. In this case, the code filters the name argument to contain only letters, which avoids injection of control characters, HTML, and so forth. (When you use templates in the next section, Flask does automatic filtering and you won't need this code.) + +1. Set a breakpoint at the first line of code in the `hello_there` function (`now = datetime.now()`) by doing any one of the following: + - With the cursor on that line, press `kb(editor.debug.action.toggleBreakpoint)`, or, + - With the cursor on that line, select the **Debug** > **Toggle Breakpoint** menu command, or, + - Click directly in the margin to the left of the line number (a faded red dot appears when hovering there). + + The breakpoint appears as a red dot in the left margin: + + ![Flask tutorial: a breakpoint set on the first line of the hello_there function](images/flask-tutorial/debug-breakpoint-set.png) + +1. Switch to **Debug** view in VS Code (using the left-side activity bar). Along the top of the Debug view, you may see "No Configurations" and a warning dot on the gear icon. Both indicators mean that you don't yet have a `launch.json` file containing debug configurations: + + ![Flask tutorial: initial view of the debug panel](images/shared/debug-panel-initial-view.png) + +1. Select the gear icon and select **Python** from the list that appears. VS Code creates and opens a `launch.json` file. This JSON file contains a number of debugging configurations, each of which is a separate JSON object within the `configuration` array. + +1. Scroll down to and examine the configuration with the name "Python: Flask (0.11.x or later)". This configuration contains `"module": "flask",`, which tells VS Code to run Python with `-m flask` when it starts the debugger. It also defines the FLASK_APP environment variable in the `env` property to identify the startup file, which is `app.py` by default, but allows you to easily specify a different file. If you want to change the host and/or port, you can use the `args` array. + + ```json + { + "name": "Python: Flask (0.11.x or later)", + "type": "python", + "request": "launch", + "module": "flask", + "env": { + "FLASK_APP": "app.py" + }, + "args": [ + "run", + "--no-debugger", + "--no-reload" + ] + }, + ``` + + > **Note**: If the `env` entry in your configuration contains `"FLASK_APP": "${workspaceFolder}/app.py"`, change it to `"FLASK_APP": "app.py"` as shown above. Otherwise you may encounter error messages like "Cannot import module C" where C is the drive letter where your project folder resides. + +1. Save `launch.json` (`kb(workbench.action.files.save)`). In the debug configuration drop-down list (which reads **Python: Current File**) select the **Python: Flask (0.11.x or later)** configuration. + + ![Flask tutorial: selecting the Flask debugging configuration](images/flask-tutorial/debug-select-configuration.png) + +1. Start the debugger by selecting the **Debug** > **Start Debugging** menu command, or selecting the green **Start Debugging** arrow next to the list (`kb(workbench.action.debug.continue)`): + + ![Flask tutorial: start debugging/continue arrow on the debug toolbar](images/flask-tutorial/debug-continue-arrow.png) + + Observe that the status bar changes color to indicate debugging: + + ![Flask tutorial: appearance of the debugging status bar](images/flask-tutorial/debug-status-bar.png) + + A debugging toolbar (shown below) also appears in VS Code containing commands in the following order: Pause (or Continue, `kb(workbench.action.debug.continue)`), Step Over (`kb(workbench.action.debug.stepOver)`), Step Into (`kb(workbench.action.debug.stepInto)`), Step Out (`kb(workbench.action.debug.stepOut)`), Restart (`kb(workbench.action.debug.restart)`), and Stop (`kb(workbench.action.debug.stop)`). See [VS Code debugging](/docs/editor/debugging.md) for a description of each command. + + ![Flask tutorial: the VS Code debug toolbar](images/flask-tutorial/debug-toolbar.png) + +1. Output appears in a "Python Debug Console" terminal. `kbstyle(Ctrl+click)` the `http://127.0.0.1:5000/` link in that terminal to open a browser to that URL. In the browser's address bar, navigate to `http://127.0.0.1:5000/hello/VSCode`. Before the page renders, VS Code pauses the program at the breakpoint you set. The small yellow arrow on the breakpoint indicates that it's the next line of code to run. + + ![Flask tutorial: VS Code paused at a breakpoint](images/flask-tutorial/debug-program-paused.png) + +1. Use Step Over to run the `now = datetime.now()` statement. + +1. On the left side of the VS Code window, you see a **Variables** pane that shows local variables, such as `now`, as well as arguments, such as `name`. Below that are panes for **Watch**, **Call Stack**, and **Breakpoints** (see [VS Code debugging](/docs/editor/debugging.md) for details). In the **Locals** section, try expanding different values. You can also double-click values (or use `kb(debug.setVariable)`) to modify them. Changing variables such as `now`, however, can break the program. Developers typically make changes only to correct values when the code didn't produce the right value to begin with. + + ![Flask tutorial: local variables and arguments in VS Code during debugging](images/flask-tutorial/debug-local-variables.png) + +1. When a program is paused, the **Debug Console** panel (which is different from the "Python Debug Console" in the Terminal panel) lets you experiment with expressions and try out bits of code using the current state of the program. For example, once you've stepped over the line `now = datetime.now()`, you might experiment with different date/time formats. In the editor, select the code that reads `now.strftime("%A, %d %B, %Y at %X")`, then right-click and select **Debug: Evaluate** to send that code to the debug console, where it runs: + + ```bash + now.strftime("%A, %d %B, %Y at %X") + 'Wednesday, 31 October, 2018 at 18:13:39' + ``` + + > **Tip**: The **Debug Console** also shows exceptions from within the app that may not appear in the terminal. For example, if you see a "Paused on exception" message in the **Call Stack** area of Debug View, switch to the **Debug Console** to see the exception message. + +1. Copy that line into the > prompt at the bottom of the debug console, and try changing the formatting: + + ```bash + now.strftime("%a, %d %B, %Y at %X") + 'Wed, 31 October, 2018 at 18:13:39' + now.strftime("%a, %d %b, %Y at %X") + 'Wed, 31 Oct, 2018 at 18:13:39' + now.strftime("%a, %d %b, %y at %X") + 'Wed, 31 Oct, 18 at 18:13:39' + ``` + + > **Note**: If you see a change you like, you can copy and paste it into the editor during a debugging session. However, those changes aren't applied until you restart the debugger. + +1. Step through a few more lines of code, if you'd like, then select Continue (`kb(workbench.action.debug.continue)`) to let the program run. The browser window shows the result: + + ![Flask tutorial: result of the modified program](images/flask-tutorial/debug-run-result.png) + +1. Close the browser and stop the debugger when you're finished. To stop the debugger, use the Stop toolbar button (the red square) or the **Debug** > **Stop Debugging** command (`kb(workbench.action.debug.stop)`). + +> **Tip**: To make it easier to repeatedly navigate to a specific URL like `http://127.0.0.1:5000/hello/VSCode`, output that URL using a `print` statement. The URL appears in the terminal where you can use `kbstyle(Ctrl+click)` to open it in a browser. + +## Go to Definition and Peek Definition commands + +During your work with Flask or any other library, you may want to examine the code in those libraries themselves. VS Code provides two convenient commands that navigate directly to the definitions of classes and other objects in any code: + +- **Go to Definition** jumps from your code into the code that defines an object. For example, in `app.py`, right-click on the `Flask` class (in the line `app = Flask(__name__)`) and select **Go to Definition** (or use `kb(editor.action.revealDefinition)`), which navigates to the class definition in the Flask library. + +- **Peek Definition** (`kb(editor.action.peekDefinition)`, also on the right-click context menu), is similar, but displays the class definition directly in the editor (making space in the editor window to avoid obscuring any code). Press `kbstyle(Escape)` to close the Peek window or use the **x** in the upper right corner. + + ![Flask tutorial: peek definition showing the Flask class inline](images/flask-tutorial/peek-definition.png) + +## Use a template to render a page + +The app you've created so far in this tutorial generates only plain text web pages from Python code. Although it's possible to generate HTML directly in code, developers avoid such a practice because it opens the app to [cross-site scripting (XSS) attacks](http://flask.pocoo.org/docs/1.0/security/#cross-site-scripting-xss). In the `hello_there` function of this tutorial, for example, one might think to format the output in code with something like `content = "

Hello there, " + clean_name + "!

`, where the result in `content` is given directly to a browser. This opening allows an attacker to place malicious HTML, including JavaScript code, in the URL that ends up in `clean_name` and thus ends up being run in the browser. + +A much better practice is to keep HTML out of your code entirely by using **templates**, so that your code is concerned only with data values and not with rendering. + +- A template is an HTML file that contains placeholders for values that the code provides at run time. The templating engine takes care of making the substitutions when rendering the page. The code, therefore, concerns itself only with data values and the template concerns itself only with markup. +- The default templating engine for Flask is [Jinja](http://jinja.pocoo.org/), which is installed automatically when you install Flask. This engine provides flexible options including automatic escaping (to prevent XSS attacks) and template inheritance. With inheritance, you can define a base page with common markup and then build upon that base with page-specific additions. + +In this section, you create a single page using a template. In the sections that follow, you configure the app to serve static files, and then create multiple pages to the app that each contains a nav bar from a base template. + +1. Inside the `hello_flask` folder, create a folder named `templates`, which is where Flask looks for templates by default. + +1. In the `templates` folder, create a file named `hello_there.html` with the contents below. This template contains two placeholders named "name" and "date", which are delineated by pairs of curly braces, `\{{` and `}}`. As you can see, you can also include formatting code in the template directly: + + ```html + + + + + Hello, Flask + + + {%if name %} + Hello there, \{{ name }}! It's \{{ date.strftime("%A, %d %B, %Y at %X") }}. + {% else %} + What's your name? Provide it after /hello/ in the URL. + {% endif %} + + + ``` + + > **Tip**: Flask developers often use the [flask-babel](https://pythonhosted.org/Flask-Babel/) extension for date formatting, rather than `strftime`, as flask-babel takes locales and timezones into consideration. + +1. In `app.py`, import Flask's `render_template` function near the top of the file: + + ```python + from flask import render_template + ``` + +1. Also in `app.py`, modify the `hello_there` function to use `render_template` to load a template and apply the named values (and add a route to recognize the case without a name). `render_template` assumes that the first argument is relative to the `templates` folder. Typically, developers name the templates the same as the functions that use them, but matching names are not required because you always refer to the exact filename in your code. + + ```python + @app.route("/hello/") + @app.route("/hello/") + def hello_there(name = None): + return render_template( + "hello_there.html", + name=name, + date=datetime.now() + ) + ``` + + You can see that the code is now much simpler, and concerned only with data values, because the markup and formatting is all contained in the template. + +1. Start the program (inside or outside of the debugger, using `kb(workbench.action.debug.run)`), navigate to a /hello/name URL, and observe the results. + +1. Also try navigating to a /hello/name URL using a name like `` to see Flask's automatic escaping at work. The "name" value shows up as plain text in the browser rather than as rendering an actual element. + +## Serve static files + +Static files are of two types. First are those files like stylesheets to which a page template can just refer directly. Such files can live in any folder in the app, but are commonly placed within a `static` folder. + +The second type are those that you want to address in code, such as when you want to implement an API endpoint that returns a static file. For this purpose, the Flask object contains a built-in method, `send_static_file`, which generates a response with a static file contained within the app's `static` folder. + +The following sections demonstrate both types of static files. + +### Refer to static files in a template + +1. In the `hello_flask` folder, create a folder named `static`. + +1. Within the `static` folder, create a file named `site.css` with the following contents. After entering this code, also observe the syntax highlighting that VS Code provides for CSS files, including a color preview: + + ```css + .message { + font-weight: 600; + color: blue; + } + ``` + +1. In `templates/hello_there.html`, add the following line before the `` tag, which creates a reference to the stylesheet. + + ```html + + ``` + + Flask's [`url_for` tag](http://flask.pocoo.org/docs/0.12/api/#flask.url_for) that's used here creates the appropriate path to the file. Because it can accept variables as arguments, `url_for` allows you to programmatically control the generated path, if desired. + +1. Also in `templates/hello_there.html`, replace the contents `` element with the following markup that uses the `message` style instead of a `` tag (and also displays a message if you just use a hello/ URL without a name): + + ```html + {%if name %} + Hello there, \{{ name }}! It's \{{ date.strftime("%A, %d %B, %Y at %X") }}. + {% else %} + What's your name? Provide it after /hello/ in the URL. + {% endif %} + ``` + +1. Run the app, navigate to a /hello/name URL, and observe that the message renders in blue. Stop the app when you're done. + +### Serve a static file from code + +1. In the `static` folder, create a JSON data file named `data.json` with the following contents (which are meaningless sample data): + + ```json + { + "01": { + "note" : "This data is very simple because we're demonstrating only the mechanism." + } + } + ``` + +1. In `app.py`, add a function with the route /api/data that returns the static data file using the `send_static_file` method: + + ```python + @app.route("/api/data") + def get_data(): + return app.send_static_file("data.json") + ``` + +1. Run the app and navigate to the /api/data endpoint to see that the static file is returned. Stop the app when you're done. + +## Create multiple templates that extend a base template + +Because most web apps have more than one page, and because those pages typically share many common elements, developers separate those common elements into a base page template that other page templates can then extend. (This is also called template inheritance.) + +Also, because you'll likely create many pages that extend the same template, it's helpful to create a code snippet in VS Code with which you can quickly initialize new page templates. A snippet helps you avoid tedious and error-prone copy-paste operations. + +The following sections walk through different parts of this process. + +### Create a base page template and styles + +A base page template in Flask contains all the shared parts of a set of pages, including references to CSS files, script files, and so forth. Base templates also define one or more **block** tags that other templates that extend the base are expected to override. A block tag is delineated by `{% block %}` and `{% endblock %}` in both the base template and extended templates. + +The following steps demonstrate creating a base template. + +1. In the `templates` folder, create a file named `layout.html` with the contents below, which contains blocks named "title" and "content". As you can see, the markup defines a simple nav bar structure with links to Home, About, and Contact pages, which you create in a later section. Each link again uses Flask's `url_for` tag to generate a link at runtime for the matching route. + + ```html + + + + + {% block title %}{% endblock %} + + + + +
+ Home + About + Contact +
+ +
+ {% block content %} + {% endblock %} +
+
+

© 2018

+
+
+ + + ``` + +1. Add the following styles to `static/site.css` below the existing "message" style, and save the file. (This walkthrough doesn't attempt to demonstrate responsive design; these styles simply generate a reasonably interesting result.) + + ```css + .navbar { + background-color: lightslategray; + font-size: 1em; + font-family: 'Trebuchet MS', 'Lucida Sans Unicode', 'Lucida Grande', 'Lucida Sans', Arial, sans-serif; + color: white; + padding: 8px 5px 8px 5px; + } + + .navbar a { + text-decoration: none; + color: inherit; + } + + .navbar-brand { + font-size: 1.2em; + font-weight: 600; + } + + .navbar-item { + font-variant: small-caps; + margin-left: 30px; + } + + .body-content { + padding: 5px; + font-family:'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; + } + ``` + +You can run the app at this point, but because you haven't made use of the base template anywhere and haven't changed any code files, the result is the same as the previous step. Complete the remaining sections to see the final effect. + +### Create a code snippet + +Because the three pages you create in the next section extend `layout.html`, it saves time to create a **code snippet** to initialize a new template file with the appropriate reference to the base template. A code snippet provides a consistent piece of code from a single source, which avoids errors that can creep in when using copy-paste from existing code. + +1. In VS Code, select the **File** (Windows/Linux) or **Code** (macOS), menu, then select **Preferences** > **User snippets**. + +1. In the list that appears, select **html**. (The option may appear as "html.json" in the **Existing Snippets** section of the list if you've created snippets previously.) + +1. After VS code opens `html.json`, add the following entry within the existing curly braces (the explanatory comments, not shown here, describe details such as how the `$0` line indicates where VS Code places the cursor after inserting a snippet): + + ```json + "Flask Tutorial: template extending layout.html": { + "prefix": "flextlayout", + "body": [ + "{% extends \"layout.html\" %}", + "{% block title %}", + "$0", + "{% endblock %}", + "{% block content %}", + "{% endblock %}" + ], + + "description": "Boilerplate template that extends layout.html" + }, + ``` + +1. Save the `html.json` file (`kb(workbench.action.files.save)`). + +1. Now, whenever you start typing the snippet's prefix, such as `flext`, VS Code provides the snippet as an autocomplete option, as shown in the next section. You can also use the **Insert Snippet** command to choose a snippet from a menu. + +For more information on code snippets in general, refer to [Creating snippets](/docs/editor/userdefinedsnippets.md). + +### Use the code snippet to add pages + +With the code snippet in place, you can quickly create templates for the Home, About, and Contact pages. + +1. In the `templates` folder, create a new file named `home.html`, Then start typing `flext` to see the snippet appear as a completion: + + ![Flask tutorial: autocompletion for the flextlayout code snippet](images/flask-tutorial/autocomplete-for-code-snippet.png) + + When you select the completion, the snippet's code appears with the cursor on the snippet's insertion point: + + ![Flask tutorial: insertion of the flextlayout code snippet](images/flask-tutorial/code-snippet-inserted.png) + +1. At the insertion point in the "title" block, write `Home`, and in the "content" block, write `

Home page for the Visual Studio Code Flask tutorial.

`, then save the file. These lines are the only unique parts of the extended page template: + +1. In the `templates` folder, create `about.html`, use the snippet to insert the boilerplate markup, insert `About us` and `

About page for the Visual Studio Code Flask tutorial.

` in the "title" and "content" blocks, respectively, then save the file. + +1. Repeat the previous step to create `templates/contact.html` using `Contact us` and `

Contact page for the Visual Studio Code Flask tutorial.

` in the two content blocks. + +1. In `app.py`, add functions for the /about/ and /contact/ routes that refer to their respective page templates. Also modify the `home` function to use the `home.html` template. + + ```python + # Replace the existing home function with the one below + @app.route("/") + def home(): + return render_template("home.html") + + # New functions + @app.route("/about/") + def about(): + return render_template("about.html") + + @app.route("/contact/") + def contact(): + return render_template("contact.html") + ``` + +### Run the app + +With all the page templates in place, save `app.py`, run the app, and open a browser to see the results. Navigate between the pages to verify that the page templates are properly extending the base template. + +![Flask tutorial: app rendering a common nav bar from the base template](images/flask-tutorial/full-app.png) + +## Optional activities + +The following sections describe additional steps that you might find helpful in your work with Python and Visual Studio Code. + +### Create a requirements.txt file for the environment + +When you share your app code through source control or some other means, it doesn't make sense to copy all the files in a virtual environment because recipients can always recreate the environment themselves. + +Accordingly, developers typically omit the virtual environment folder from source control and instead describe the app's dependencies using a `requirements.txt` file. + +Although you can create the file by hand, you can also use the `pip freeze` command to generate the file based on the exact libraries installed in the activated environment: + +1. With your chosen environment selected using the **Python: Select Interpreter** command, run the **Terminal: Create New Integrated Terminal** command (`kb(workbench.action.terminal.new)`)) to open a terminal with that environment activated. + +1. In the terminal, run `pip freeze > requirements.txt` to create the `requirements.txt` file in your project folder. + +Anyone (or any build server) that receives a copy of the project needs only to run the `pip install -r requirements.txt` command to reinstall the packages in the original the environment. (The recipient still needs to create their own virtual environment, however.) + +> **Note**: `pip freeze` lists all the Python packages you have installed in the current environment, including packages you aren't currently using. The command also lists packages with exact version numbers, which you might want to convert to ranges for more flexibility in the future. For more information, see [Requirements files](https://pip.readthedocs.io/en/stable/user_guide/#requirements-files) in the pip command documentation. + +### Refactor the project to support further development + +Throughout this Flask tutorial, all the app code is contained in a single `app.py` file. To allow for further development and to separate concerns, it's helpful to refactor the pieces of `app.py` into separate files. + +1. In your project folder, create a folder for the app, such as `hello_app`, to separate its files from other project-level files like `requirements.txt` and the `.vscode` folder where VS Code stores settings and debug configuration files. + +1. Move the `static` and `templates` folders into `hello_app`, because these folders certainly contain app code. + +1. In the `hello_app` folder, create a file named `views.py` that contains the routings and the view functions: + + ```python + from flask import Flask + from flask import render_template + from datetime import datetime + from . import app + + @app.route("/") + def home(): + return render_template("home.html") + + @app.route("/about/") + def about(): + return render_template("about.html") + + @app.route("/contact/") + def contact(): + return render_template("contact.html") + + @app.route("/hello/") + @app.route("/hello/") + def hello_there(name): + return render_template( + "hello_there.html", + name=name, + date=datetime.now() + ) + + @app.route("/api/data") + def get_data(): + return app.send_static_file("data.json") + ``` + +1. Optional: Right-click in the editor and select the **Sort Imports** command, which consolidates imports from identical modules, removes unused imports, and sorts your import statements. Using the command on the code above in `views.py` changes the imports as follows (you can remove the extra lines, of course): + + ```python + from datetime import datetime + + from flask import Flask, render_template + + from . import app + ``` + +1. In the `hello_app` folder, create a file `__init__.py` with the following contents: + + ```python + import flask + app = flask.Flask(__name__) + ``` + +1. In the `hello_app` folder, create a file `webapp.py` with the following contents: + + ```python + # Entry point for the application. + from . import app # For application discovery by the 'flask' command. + from . import views # For import side-effects of setting up routes. + ``` + +1. Open the debug configuration file `launch.json` and update the `env` property as follows to point to the startup object: + + ```json + "env": { + "FLASK_APP": "hello_app.webapp" + }, + ``` + +1. Delete the original `app.py` file in the project root, as its contents have been moved into other app files. + +1. Your project's structure should now be similar to the following: + + ![Flask tutorial: modified project structure with separate files and folders for parts of the app](images/flask-tutorial/project-structure.png) + +1. Run the app in the debugger again to make sure everything works. To run the app outside of the VS Code debugger, use the following steps: + 1. Set an environment variable for `FLASK_APP`. On Linux and macOS, use `export set FLASK_APP=webapp`; on Windows use `set FLASK_APP=webapp`. + 1. In the `hello_app` folder, launch the program using `python3 -m flask run` (Linux/macOS) or `python -m flask run` (Windows). + +If you have any problems, feel free to file an issue for this tutorial in the [VS Code documentation repository](https://github.com/Microsoft/vscode-docs/issues). + +## Next steps + +Congratulations on completing this walkthrough of working with Flask in Visual Studio Code! + +The completed code project from this tutorial can be found on GitHub: [python-sample-vscode-flask-tutorial](https://github.com/Microsoft/python-sample-vscode-flask-tutorial). + +Because this tutorial has only scratched the surface of page templates, refer to the [Jinja2 documentation](http://jinja.pocoo.org/docs/) for more information about templates. The [Template Designer Documentation](http://jinja.pocoo.org/docs/templates/#synopsis) contains all the details on the template language. You might also want to review the [official Flask tutorial](http://flask.pocoo.org/docs/1.0/tutorial/). + +To try your app on a production website, check out the tutorial [Deploy Python apps to Azure App Service using Docker Containers](/docs/python/tutorial-deploy-containers.md). Azure also offers a standard container, [App Service on Linux (Preview)](/docs/python/tutorial-deploy-app-service-on-linux.md), to which you deploy web apps from within VS Code. + +You may also want to review the following articles in the VS Code docs that are relevant to Python: + +- [Editing Python code](/docs/python/editing.md) +- [Linting](/docs/python/linting.md) +- [Managing Python environments](/docs/python/environments.md) +- [Debugging Python](/docs/python/debugging.md) +- [Unit testing](/docs/python/unit-testing.md) + +If you encountered any problems in the course of this tutorial, feel free to file an issue in the [VS Code documentation repository](https://github.com/Microsoft/vscode-docs/issues). diff --git a/docs/python/unit-testing.md b/docs/python/unit-testing.md new file mode 100644 index 0000000000000000000000000000000000000000..52865eba7fe0e4f7bcef5e9f071a832feeb40c43 --- /dev/null +++ b/docs/python/unit-testing.md @@ -0,0 +1,338 @@ +--- +Order: 7 +Area: python +TOCTitle: Unit Testing +ContentId: 9480bef3-4dfc-4671-a454-b9252567bc60 +PageTitle: Unit Testing Python in Visual Studio Code +DateApproved: 03/07/2019 +MetaDescription: Unit Testing Python in Visual Studio Code including the Test Explorer +MetaSocialImage: images/tutorial/social.png +--- +# Python unit testing in Visual Studio Code + +The [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) supports unit testing with Python's built-in [unittest](https://docs.python.org/3/library/unittest.html) framework as well as [pytest](https://docs.pytest.org/en/latest/). [Nose](https://nose.readthedocs.io/en/latest/) is also supported, although the framework itself is in maintenance mode. + +After [enabling a test framework](#enable-a-test-framework), use the **Python: Discover Unit Tests** command to [scan the project for tests](#test-discovery) according to the discovery patterns of the currently selected test framework. Once discovered, Visual Studio Code provides a variety of means to [run tests](#run-tests) and [debug tests](#debug-tests). VS Code displays unit test output in the **Python Test Log** panel, including errors caused when a test framework is not installed. With PyTest, failed tests also appear in the **Problems** panel. + +## A little background on unit testing + +(If you're already familiar with unit testing, you can skip to the [walkthroughs](#example-test-walkthroughs).) + +A *unit* is a specific piece of code to be tested, such as a function or a class. *Unit tests* are then other pieces of code that specifically exercise the code unit with a full range of different inputs, including boundary and edge cases. + +For example, say you have a function to validate the format of an account number that a user enters in a web form: + +```python +def validate_account_number_format(account_string): + # Return false if invalid, true if valid + # ... +``` + +Unit tests are concerned only with the unit's *interface*—its arguments and return values—not with its implementation (which is why no code is shown here in the function body; often you'd be using other well-tested libraries to help implement the function). In this example, the function accepts any string and returns true if that string contains a properly formatted account number, false otherwise. + +To thoroughly test this function, you want to throw at it every conceivable input: valid strings, mistyped strings (off by one or two characters, or containing invalid characters), strings that are too short or too long, blank strings, null arguments, strings containing control characters (non-text codes), string containing HTML, strings containing injection attacks (such as SQL commands or JavaScript code), and so on. It's especially important to test security cases like injection attacks if the validated string is later used in database queries or displayed in the app's UI. + +For each input, you then define the function's expected return value (or values). In this example, again, the function should return true for only properly formatted strings. (Whether the number itself is a real account is a different matter that would be handled elsewhere through a database query.) + +With all the arguments and expected return values in hand, you now write the tests themselves, which are simply pieces of code that call the function with a particular input, then compare the actual return value with the expected return value (this comparison is called an *assertion*): + +```python +# Import the code to be tested +import validator + +# Import the unit test framework (this is a hypothetical module) +import test_framework + +# This is a generalized example, not specific to a test framework +class Test_TestAccountValidator(test_framework.TestBaseClass): + def test_validator_valid_string(): + # The exact assertion call depends on the framework as well + assert(validate_account_number_format("1234567890"), true) + + # ... + + def test_validator_blank_string(): + # The exact assertion call depends on the framework as well + assert(validate_account_number_format(""), false) + + # ... + + def test_validator_sql_injection(): + # The exact assertion call depends on the framework as well + assert(validate_account_number_format("drop database master"), false) + + # ... tests for all other cases +``` + +The exact structure of the code depends on the unit test framework you're using, and specific examples are provided later in this article. In any case, as you can see, each test is very simple: invoke the function with an argument and assert the expected return value. + +The combined results of all the tests is your test report, which tells you whether the function (the unit), is behaving as expected across all test cases. That is, when a unit passes all of its tests, you can be confident that it's functioning properly. (The practice of *test-driven development* is where you actually write the tests first, then write the code to pass more and more tests until all of them pass.) + +Because unit tests are small, isolated piece of code (in unit testing you avoid external dependencies and use mock data or otherwise simulated inputs), they're quick and inexpensive to run. This characteristic means that you can run unit tests early and often. Developers typically run unit tests even before committing code to a repository; gated check-in systems can also run unit tests before merging a commit. Many continuous integration systems also run unit tests after every build. Running the unit test early and often means that you quickly catch *regressions,* which are unexpected changes in the behavior of code that previously passed all its unit tests. Because the test failure can easily be traced to a particular code change, it's easy to find and remedy the cause of the failure, which is undoubtedly better than discovering a problem much later in the process! + +For a general background on unit testing, see [Unit Testing](https://wikipedia.org/wiki/Unit_testing) on Wikipedia. For a variety of useful unit test examples, see [https://github.com/gwtw/py-sorting](https://github.com/gwtw/py-sorting), a repository with tests for different sorting algorithms. + +## Example test walkthroughs + +Python tests are Python classes that reside in separate files from the code being tested. Each test framework specifies the structure and naming of tests and test files. Once you write tests and enable a test framework, VS Code locates those tests and provides you with various commands to run and debug them. + +For this section, create a folder and open it in VS Code. Then create a file named `inc_dec.py` with the following code to be tested: + +```python +def increment(x): + return x + 1 + +def decrement(x): + return x - 1 +``` + +With this code, you can experience working with tests in VS Code as described in the sections that follow. + +## Enable a test framework + +Unit testing in Python is disabled by default. To enable unit testing, set *one and only one* of the following settings to true: `python.unitTest.unittestEnabled`, `python.unitTest.pyTestEnabled`, and `python.unitTest.nosetestsEnabled`. Each framework also has specific configuration settings as described under [Test configuration settings](#test-configuration-settings). + +It's important that you enable only a single test framework at a time. For this reason, when you enable one framework also be sure to disable the others. + +When you enable a test framework, VS Code prompts you to install the framework package if it's not already present in the currently activated environment: + +![VS Code prompt to install a test framework when enabled](images/unit-testing/install-framework.png) + +### Settings to enable unittest + +```json +"python.unitTest.unittestEnabled": true, +"python.unitTest.pyTestEnabled": false, +"python.unitTest.nosetestsEnabled": false, +``` + +### Settings to enable pytest + +```json +"python.unitTest.unittestEnabled": false, +"python.unitTest.pyTestEnabled": true, +"python.unitTest.nosetestsEnabled": false, +``` + +### Settings to enable Nose + +```json +"python.unitTest.unittestEnabled": false, +"python.unitTest.pyTestEnabled": false, +"python.unitTest.nosetestsEnabled": true, +``` + +## Create tests + +Each test framework has its own conventions for naming test files and structuring the tests within, as described in the following sections. Each case includes two test methods, one of which is intentionally set to fail for the purposes of demonstration. + +Because Nose is in maintenance mode and not recommended for new projects, only unittest and pytest examples are shown in the sections that follow. (Nose2, the successor to Nose, is just unittest with plugins, and so it follows the unittest patterns shown here.) + +### Tests in unittest + +Create a file named `test_unittest.py` that contains a test class with two test methods: + +```python +import inc_dec # The code to test +import unittest # The test framework + +class Test_TestIncrementDecrement(unittest.TestCase): + def test_increment(self): + self.assertEqual(inc_dec.increment(3), 4) + + def test_decrement(self): + self.assertEqual(inc_dec.decrement(3), 4) + +if __name__ == '__main__': + unittest.main() +``` + +### Tests in pytest + +Create a file named `test_pytest.py` that contains two test methods: + +```python +import inc_dec # The code to test + +def test_increment(): + assert inc_dec.increment(3) == 4 + +def test_decrement(): + assert inc_dec.decrement(3) == 4 +``` + +## Test discovery + +VS Code uses the currently enabled unit testing framework to discover tests. You can trigger test discovery at any time using the **Python: Discover Unit Tests** command. + +`python.unitTest.autoTestDiscoverOnSaveEnabled` is set to `true` by default, meaning test discovery is performed automatically whenever you save a test file. To disable this feature, set the value to `false`. + +Test discovery applies the discovery patterns for the current framework (which can be customized using the [Test configuration settings](#test-configuration-settings)). The default behavior is as follows: + +- `python.unitTest.unittestArgs`: Looks for any Python (`.py`) file with "test" in the name in the top-level project folder. All test files must be importable modules or packages. You can customize the file matching pattern with the `-p` configuration setting, and customize the folder with the `-t` setting. + +- `python.unitTest.pyTestArgs`: Looks for any Python (`.py`) file whose name begins with "test\_" or ends with "\_test", located anywhere within the current folder and all subfolders. + +> **Tip**: Sometimes unit tests placed in subfolders aren't discovered because such test files cannot be imported. To make them importable, create an empty file named `__init__.py` in that folder. + +If discovery succeeds, the status bar shows **Run Tests** instead: + +![Status bar showing successful test discovery failed](images/unit-testing/discovery-succeeded-status-bar.png) + +If discovery fails (for example, the test framework isn't installed), you see a notification on the status bar. Selecting the notification provides more information: + +![Status bar showing that test discovery failed](images/unit-testing/discovery-failed-status-bar.png) + +Once VS Code recognizes tests, it provides several ways to run those tests as described in [Run tests](#run-tests). The most obvious means are CodeLens adornments that appear directly in the editor and allow you to easily run a single test method or, with unittest, a test class: + +![Test adornments that appear in the VS Code editor for unittest code](images/unit-testing/editor-adornments-unittest.png) + +![Test adornments that appear in the VS Code editor for pytest code](images/unit-testing/editor-adornments-pytest.png) + +> **Note**: At present, the Python extension doesn't provide a setting to turn the adornments on or off. To suggest a different behavior, file an issue on the [vscode-python repository](https://github.com/Microsoft/vscode-python/issues). + +For Python, test discovery also activates the **Test Explorer** with an icon on the VS Code activity bar. The **Test Explorer** helps you visualize, navigate, and run unit tests: + +![The VS Code Test Explorer for Python unit tests](images/unit-testing/test-explorer.png) + +## Run tests + +You run tests using any of the following actions: + +- With a test file open, select the **Run Test** CodeLens adornment that appears above a test method or a class, as shown in the previous section. This command runs only that one method or only those tests in the class. + +- Select **Run Tests** on the Status Bar (which can change appearance based on results), + + ![Test command on the VS Code status bar](images/unit-testing/discovery-succeeded-status-bar.png) + + then select one of the commands like **Run All Unit Tests** or **Run Failed Unit Tests**: + + ![Test commands that appear after using the Run Tests status bar command](images/unit-testing/run-test-commands.png) + +- In **Test Explorer**: + + - To run all discovered tests, select the play button at the top of **Test Explorer**: + + ![Running all tests through Test Explorer](images/unit-testing/test-explorer-run-all-tests.png) + + - To run a specific group of tests, or a single test, select the file, class, or test, then select the play button to the right of that item: + + ![Running tests at specific scopes through Test Explorer](images/unit-testing/test-explorer-run-scoped-tests.png) + +- Right-click a file in Explorer and select **Run All Unit Tests**, which runs the tests in that one file. + +- From the **Command Palette**, select any of the run unit test commands: + + ![Python unit testing commands on the Command Palette](images/unit-testing/commands.png) + + | Command | Description | + | --- | --- | + | Debug All Unit Tests | See [Debug tests](#debug-tests). | + | Debug Unit Test Method | See [Debug tests](#debug-tests). | + | Run All Unit Tests | Searches for and runs all unit tests in the workspace and its subfolders. | + | Run Current Unit Test File | Runs the test in the file that's currently viewed in the editor. | + | Run Failed Unit Tests | Re-runs any tests that failed in a previous test run. Runs all test if no tests have been run yet. | + | Run Unit Test File | Prompts for a specific test filename, then runs the test in that file. | + | Run Unit Test Method | Prompts for the name of a test to run, providing auto-completion for test names. | + | Show Unit Test Output | Opens the Python Test Log panel with information about passing and failing tests, as well as errors and skipped tests. | + +After a test run, VS Code displays results directly with the CodeLens adornments in the editor and in **Test Explorer**. Results are shown both for individual tests as well as any classes and files containing those tests. Failed tests are also adorned in the editor with a red underline. + +![Test results on a unittest class and in Test Explorer](images/unit-testing/test-results.png) + +VS Code also shows test results in the **Python Test Log** output panel (use the **View** > **Output** menu command to show the **Output** panel, then select **Python Test Log** from the drop-down on the right side): + +![Test results in the Python Test Log output panel](images/unit-testing/python-test-log-output.png) + +With PyTest, failed tests also appear in the **Problems** panel, where you can double-click on an issue to navigate directly to the test: + +![Test results for pytest in the Problems panel](images/unit-testing/python-test-problems-output.png) + +## Debug tests + +Because unit tests themselves are source code, they are prone to code defects just like the production code they test. For this reason, you may occasionally need to step through and analyze unit tests in the debugger. + +For example, the `test_decrement` functions given earlier are failing because the assertion itself is faulty. The following steps demonstrate how to analyze the test: + +1. Set a breakpoint on first the line in the `test_decrement` function. + +1. Select the **Debug Test** adornment above that function or the "bug" icon for that test in **Test Explorer**. VS Code starts the debugger and pauses at the breakpoint. + +1. In the **Debug Console** panel, enter `inc_dec.decrement(3)` to see that the actual result is 2, whereas the expected result specified in the test is the incorrect value of 4. + +1. Stop the debugger and correct the faulty code: + + ```python + # unittest + self.assertEqual(inc_dec.decrement(3), 2) + + # pytest + assert inc_dec.decrement(3) == 4 + ``` + +1. Save the file and run the tests again to confirm that they pass, and see that the CodeLens adornments also indicate passing status. + + > **Note**: running or debugging a unit test does not automatically save the test file. Always be sure to save changes to a test before running it, otherwise you'll likely be confused by the results because they still reflect the previous version of the file! + +The **Python: Debug All Tests** and **Python: Debug Unit Test Method** commands (on both the Command Palette and Status Bar menu) launch the debugger for all tests and a single test method, respectively. You can also use the "bug" icons in **Test Explorer** to launch the debugger for all tests in a selected scope as well as all discovered tests. + +The debugger works the same for unit tests as for other Python code, including breakpoints, variable inspection, and so on. For more information, see [Python debugging configurations](/docs/python/debugging.md) and the general VS Code [Debugging](/docs/editor/debugging.md) article. + +## Test configuration settings + +The behavior of unit testing with Python is driven by both general settings and settings that are specific to whichever framework you've enabled. + +### General settings + +| Setting
(python.unitTest.) | Default | Description | +| --- | --- | --- | +| autoTestDiscoverOnSaveEnabled | `true` | Specifies whether to enable or disable auto run test discovery when saving a unit test file. | +| cwd | null | Specifies an optional working directory for unit tests. | +| debugPort | `3000` | Port number used for debugging of UnitTest tests. | +| outputWindow | `"Python Test Log"` | The window to use for unit test output. | +| promptToConfigure | `true` | Specifies whether VS Code prompts to configure a test framework if potential tests are discovered. | + +### Unittest configuration settings + +| Setting
(python.unitTest.) | Default | Description | +| --- | --- | --- | +| unittestEnabled | `false` | Specifies whether UnitTest is enabled as the test framework. All other frameworks should be disabled. | +| unittestArgs | `["-v", "-s", ".", "-p", "*test*.py"]` | Arguments to pass to unittest, where each element that's separated by a space is a separate item in the list. See below for a description of the defaults. | + +The default arguments for UnitTest are as follows: + +- `-v` sets default verbosity. Remove this argument for simpler output. +- `-s .` specifies the starting directory for discovering tests. If you have tests in a "test" folder, change the argument to `-s test` (meaning `"-s", "test"` in the arguments array). +- `-p *test*.py` is the discovery pattern used to look for tests. In this case, it's any `.py` file that includes the word "test". If you name test files differently, such as appending "\_test" to every filename, then use a pattern like `*_test.py` in the appropriate argument of the array. + +To stop a test run on the first failure, add the fail fast option `"-f"` to the arguments array. + +See [unittest command-line interface](https://docs.python.org/3/library/unittest.html#command-line-interface) for the full set of available options. + +### Pytest configuration settings + +| Setting
(python.unitTest.) | Default | Description | +| --- | --- | --- | +| pyTestEnabled | `false` | Specifies whether PyTest is enabled as the test framework. All other frameworks should be disabled. | +| pyTestPath | `"pytest"` | Path to PyTest. Use a full path if PyTest is located outside the current environment. | +| pyTestArgs | `[]` | Arguments to pass to PyTest, where each element that's separated by a space is a separate item in the list. See [PyTest command line options](https://docs.pytest.org/en/latest/customize.html#command-line-options-and-configuration-file-settings). | + +You can also configure pytest using a `pytest.ini` file as described on [PyTest Configuration](https://docs.pytest.org/en/latest/customize.html). + +> **Note** +> If you have the pytest-cov coverage module installed, VS Code doesn't stop at breakpoints while debugging because pytest-cov is using the same technique to access the source code being run. To prevent this behavior, include `--no-cov` in `pyTestArgs` when debugging tests. (For more information, see [Debuggers and PyCharm](https://pytest-cov.readthedocs.io/en/latest/debuggers.html) in the pytest-cov documentation.) + +### Nose configuration settings + +| Setting
(python.unitTest.) | Default | Description | +| --- | --- | --- | +| nosetestsEnabled | `false` | Specifies whether Nose is enabled as the test framework. All other frameworks should be disabled. | +| nosetestPath | `"nosetests"` | Path to Nose. Use a full path if Nose is located outside the current environment. | +| nosetestArgs | `[]` | Arguments to pass to Nose, where each element that's separated by a space is a separate item in the list. See [Nose usage options](https://nose.readthedocs.io/en/latest/usage.html#options). | + +You can also configure nose with a `.noserc` or `nose.cfg` file as described on [Nose configuration](https://nose.readthedocs.io/en/latest/usage.html#configuration). + +## See also + +- [Python environments](/docs/python/environments.md) - Control which Python interpreter is used for editing and debugging. +- [Settings reference](/docs/python/settings-reference.md) - Explore the full range of Python-related settings in VS Code. diff --git a/docs/setup/additional-components.md b/docs/setup/additional-components.md new file mode 100644 index 0000000000000000000000000000000000000000..12952e6fd5fa2875d80e58cc71fb2dc5f7a1234f --- /dev/null +++ b/docs/setup/additional-components.md @@ -0,0 +1,52 @@ +--- +Order: 6 +Area: setup +TOCTitle: Additional Components +ContentId: 243B79C2-819F-4257-B80D-2CD9CCB04C84 +PageTitle: Setting up additional components to use with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Setting up additional components to use with Visual Studio Code. +--- +# Additional components and tools + +Visual Studio Code is a small download by design and only includes the minimum number of components shared across most development workflows. Basic functionality like the editor, file management, window management, and preference settings are included. A JavaScript/TypeScript language service and Node.js debugger are also part of the base install. + +If you are used to working with larger, monolithic development tools (IDEs), you may be surprised that your scenarios aren't completely supported out of the box. For example, there isn't a **File** > **New Project** dialog with pre-installed project templates. Most VS Code users will need to install additional components depending on their specific needs. + +## Commonly used components + +Here are a few commonly installed components: + +- [Git](https://git-scm.com/download) - VS Code has built-in support for source code control using Git but requires Git to be installed separately. +- [Node.js (includes npm)](https://nodejs.org/) - A platform and runtime for building and running JavaScript applications. +- [TypeScript](https://www.typescriptlang.org) - The TypeScript compiler, `tsc`, for transpiling TypeScript to JavaScript. + +You'll find the components above mentioned often in our documentation and walkthroughs. + +## VS Code extensions + +You can extend the VS Code editor itself through [extensions](/docs/editor/extension-gallery.md). The VS Code community has built hundreds of useful extensions available on the VS Code [Marketplace](https://marketplace.visualstudio.com/VSCode). + +
+ +The extensions shown above are the current most popular on Marketplace. Click on an extension tile above to read the description and reviews of the extension. + +## Additional tools + +Visual Studio Code integrates with existing tool chains. We think the following tools will enhance your development experiences. + +- [Yeoman](http://yeoman.io/) - An application scaffolding tool, a command line version of **File** > **New Project**. +- [generator-aspnet](https://www.npmjs.com/package/generator-aspnet) - A Yeoman generator for scaffolding **ASP.NET Core** applications. +- [generator-hottowel](https://github.com/johnpapa/generator-hottowel) - A Yeoman generator for quickly creating **AngularJS** applications. +- [Express](https://expressjs.com/) - An application framework for Node.js applications using the **Jade** template engine. +- [Gulp](https://gulpjs.com/) - A streaming task runner system which integrates easily with VS Code tasks. +- [Mocha](https://mochajs.org/) - A JavaScript test framework that runs on Node.js. +- [Yarn](https://yarnpkg.com/) - A dependency manager and alternative to npm. + +>**Note:** Most of these tools require Node.js and the npm package manager to install and use. + +## Next steps + +* [User Interface](/docs/getstarted/userinterface.md) - A quick orientation around VS Code. +* [User/Workspace Settings](/docs/getstarted/settings.md) - Learn how to configure VS Code to your preferences through settings. +* [Languages](/docs/languages/overview.md) - VS Code supports many programming languages out-of-the-box as well as many more through community created extensions. diff --git a/docs/setup/images/mac/shell-command.png b/docs/setup/images/mac/shell-command.png new file mode 100644 index 0000000000000000000000000000000000000000..fd0bbf328d5f9713ee5dd7b40261ef8df3d64058 Binary files /dev/null and b/docs/setup/images/mac/shell-command.png differ diff --git a/docs/setup/images/mac/touchbar.gif b/docs/setup/images/mac/touchbar.gif new file mode 100644 index 0000000000000000000000000000000000000000..f923c60661a0a892a477d0fe1b81e2d07c7adce6 --- /dev/null +++ b/docs/setup/images/mac/touchbar.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5122fbf3d4490552fa5b2bfe83ae26a6065d415d2c456c6603d0b035e1c8300c +size 205581 diff --git a/docs/setup/images/network/proxy.png b/docs/setup/images/network/proxy.png new file mode 100644 index 0000000000000000000000000000000000000000..c10d4cf5a458f568d757434c46c6ee39423c6c37 Binary files /dev/null and b/docs/setup/images/network/proxy.png differ diff --git a/docs/setup/images/quicksetup/QuickSetup.png b/docs/setup/images/quicksetup/QuickSetup.png new file mode 100644 index 0000000000000000000000000000000000000000..133f8f18d29918cfe6b227cb4dda414506edfbbf --- /dev/null +++ b/docs/setup/images/quicksetup/QuickSetup.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:00bbd5e39735ebbcd0bb6822d7a4d1eb87e8b276d360816be9cb3b60cfc9aae9 +size 109809 diff --git a/docs/setup/linux.md b/docs/setup/linux.md new file mode 100644 index 0000000000000000000000000000000000000000..d76964ae21d057780d5014f89a7171a378f2bd06 --- /dev/null +++ b/docs/setup/linux.md @@ -0,0 +1,269 @@ +--- +Order: 2 +Area: setup +TOCTitle: Linux +ContentId: 7FDF94DB-3527-4296-BE1C-493495B89408 +PageTitle: Running Visual Studio Code on Linux +DateApproved: 3/7/2019 +MetaDescription: Get Visual Studio Code up and running on Linux. +--- +# Visual Studio Code on Linux + +## Installation + +### Debian and Ubuntu based distributions + +The easiest way to install Visual Studio Code for Debian/Ubuntu based distributions is to download and install the [.deb package (64-bit)](https://go.microsoft.com/fwlink/?LinkID=760868), either through the graphical software center if it's available, or through the command line with: + +```bash +sudo apt install ./.deb + +# If you're on an older Linux distribution, you will need to run this instead: +# sudo dpkg -i .deb +# sudo apt-get install -f # Install dependencies +``` + +Installing the .deb package will automatically install the apt repository and signing key to enable auto-updating using the system's package manager. Note that 32-bit and .tar.gz binaries are also available on the [download page](/Download). + +The repository and key can also be installed manually with the following script: + +```bash +curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg +sudo install -o root -g root -m 644 microsoft.gpg /etc/apt/trusted.gpg.d/ +sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/vscode stable main" > /etc/apt/sources.list.d/vscode.list' +``` + +Then update the package cache and install the package using: + +```bash +sudo apt-get install apt-transport-https +sudo apt-get update +sudo apt-get install code # or code-insiders +``` + +### RHEL, Fedora and CentOS based distributions + +We currently ship the stable 64-bit VS Code in a yum repository, the following script will install the key and repository: + +```bash +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc +sudo sh -c 'echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" > /etc/yum.repos.d/vscode.repo' +``` + +Then update the package cache and install the package using `dnf` (Fedora 22 and above): + +```bash +dnf check-update +sudo dnf install code +``` + +Or on older versions using `yum`: + +```bash +yum check-update +sudo yum install code +``` + +Note that due to the manual signing process and the system we use to publish, the yum repo may lag behind and not get the latest version of VS Code immediately. + +### openSUSE and SLE based distributions + +The yum repository above also works for openSUSE and SLE based systems, the following script will install the key and repository: + +```bash +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc +sudo sh -c 'echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\ntype=rpm-md\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" > /etc/zypp/repos.d/vscode.repo' +``` + +Then update the package cache and install the package using: + +```bash +sudo zypper refresh +sudo zypper install code +``` + +### AUR package for Arch Linux + +There is a community maintained Arch User Repository (AUR) [package for VS Code](https://aur.archlinux.org/packages/visual-studio-code-bin). + +To get more information about the installation from the AUR, please consult the following wiki entry: +[Install AUR Packages](https://wiki.archlinux.org/index.php/Arch_User_Repository#Build_and_install_the_package). + + +### Nix package for NixOS (or any Linux distribution using Nix package manager) + +There is a community maintained [Nix package](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vscode/default.nix) in the nixpkgs repository. In order to install it using Nix, set `allowUnfree` option to true in your `config.nix` and execute: + +```bash +nix-env -i vscode +``` + +### Installing .rpm package manually + +The [.rpm package (64-bit)](https://go.microsoft.com/fwlink/?LinkID=760867) can also be manually downloaded and installed, however auto-updating won't work unless the repository above is installed. Once downloaded it can be installed using your package manager, for example with `dnf`: + +```bash +sudo dnf install .rpm +``` + +Note that 32-bit and .tar.gz binaries are also available on the [download page](/Download). + +## Updates + +VS Code ships monthly and you can see when a new release is available by checking [Updates](/updates). If the VS Code repository was installed correctly, then your system package manager should handle auto-updating in the same way as other packages on the system. + +## Node.js + +Node.js is a popular platform and runtime for easily building and running JavaScript applications. It also includes [npm](https://www.npmjs.com/), a Package Manager for Node.js modules. You'll see Node.js and npm mentioned frequently in our documentation and some optional VS Code tooling requires Node.js (for example, the VS Code [extension generator](/api/get-started/your-first-extension.md)). + +If you'd like to install Node.js on Linux, see [Installing Node.js via package manager](https://nodejs.org/en/download/package-manager) to find the Node.js package and installation instructions tailored to your Linux distribution. You can also install and support multi version of Node.js by using the [Node Version Manager](https://github.com/creationix/nvm). + +To learn more about JavaScript and Node.js, see our [Node.js tutorial](/docs/nodejs/nodejs-tutorial.md), where you'll learn about running and debugging Node.js applications with VS Code. + +## Setting VS Code as the default text editor + +### xdg-open + +You can set the default text editor for text files (`text/plain`) that is used by `xdg-open` with the following command: + +```bash +xdg-mime default code.desktop text/plain +``` + +### Debian alternatives system + +Debian-based distributions allow setting a default *editor* using the [alternatives system](https://wiki.debian.org/DebianAlternatives), without concern for the MIME type. You can set this by running the following and selecting code: + +```bash +sudo update-alternatives --set editor /usr/bin/code +``` + +## Next steps + +Once you have installed VS Code, these topics will help you learn more about it: + +* [Additional Components](/docs/setup/additional-components.md) - Learn how to install Git, Node.js, TypeScript and tools like Yeoman. +* [User Interface](/docs/getstarted/userinterface.md) - A quick orientation to VS Code. +* [User/Workspace Settings](/docs/getstarted/settings.md) - Learn how to configure VS Code to your preferences through settings. + +## Common questions + +### Azure VM Issues + +I'm getting a "Running without the SUID sandbox" error? + +You can safely ignore this error. + +### Debian and moving files to trash + +If you see an error when deleting files from the VS Code Explorer on the Debian operating system, it might be because the trash implementation that VS Code is using is not there. + +Run these commands to solve this issue: + +```bash +sudo apt-get install gvfs-bin +``` + +### "Visual Studio Code is unable to watch for file changes in this large workspace" (error ENOSPC) + +When you see this notification, it indicates that the VS Code file watcher is running out of handles because the workspace is large and contains many files. The current limit can be viewed by running: + +```bash +cat /proc/sys/fs/inotify/max_user_watches +``` + +The limit can be increased to its maximum by editing `/etc/sysctl.conf` and adding this line to the end of the file: + +```bash +fs.inotify.max_user_watches=524288 +``` + +The new value can then be loaded in by running `sudo sysctl -p`. Note that [Arch Linux](https://www.archlinux.org/) works a little differently, [view this page for advice](https://github.com/guard/listen/wiki/Increasing-the-amount-of-inotify-watchers). + +While 524,288 is the maximum number of files that can be watched, if you're in an environment that is particularly memory constrained, you may wish to lower the number. Each file watch [takes up 540 bytes (32-bit) or ~1kB (64-bit)](https://stackoverflow.com/a/7091897/1156119), so assuming that all 524,288 watches are consumed, that results in an upper bound of around 256MB (32-bit) or 512MB (64-bit). + +Another option is to exclude specific workspace directories from the VS Code file watcher with the `files.watcherExclude` [setting](/docs/getstarted/settings.md). The default for `files.watcherExclude` excludes `node_modules` and some folders under `.git`, but you can add other directories that you don't want VS Code to track. + +```json +"files.watcherExclude": { + "**/.git/objects/**": true, + "**/.git/subtree-cache/**": true, + "**/node_modules/*/**": true + } +``` + +### I can't see Chinese characters in Ubuntu + +We're working on a fix. In the meantime, open the application menu, then choose **File** > **Preferences** > **Settings**. In the **Text Editor** > **Font** section, set "Font Family" to `Droid Sans Mono, Droid Sans Fallback`. If you'd rather edit the `settings.json` file directly, set `editor.fontFamily` as shown: + +```json + "editor.fontFamily": "Droid Sans Mono, Droid Sans Fallback" +``` + +### Package git is not installed + +This error can appear during installation and is typically caused by the package manager's lists being out of date. Try updating them and installing again: + +```bash +# For .deb +sudo apt-get update + +# For .rpm (Fedora 21 and below) +sudo yum update + +# For .rpm (Fedora 22 and above) +sudo dnf update +``` + +### The code bin command does not bring the window to the foreground on Ubuntu + +Running `code .` on Ubuntu when VS Code is already open in the current directory will not bring VS Code into the foreground. This is a feature of the OS which can be disabled using `ccsm`. + +```bash +# Install +sudo apt-get update +sudo apt-get install compizconfig-settings-manager + +# Run +ccsm +``` + +Under **General** > **General Options** > **Focus & Raise Behaviour**, set "Focus Prevention Level" to "Off". Remember this is an OS-level setting that will apply to all applications, not just VS Code. + +### Cannot install .deb package due to "/etc/apt/sources.list.d/vscode.list: No such file or directory" + +This can happen when `sources.list.d` doesn't exist or you don't have access to create the file. To fix this, try manually creating the folder and an empty `vscode.list` file: + +```bash +sudo mkdir /etc/apt/sources.list.d +sudo touch /etc/apt/sources.list.d/vscode.list +``` + +### Cannot move or resize the window while X forwarding a remote window + +If you are using X forwarding to use VS Code remotely, you will need to use the native title bar to ensure you can properly manipulate the window. You can switch to using it by setting `window.titleBarStyle` to `native`. + +### Using the custom title bar + +The custom title bar and menus were enabled by default on Linux for several months. The custom title bar has been a success on Windows, but the customer response on Linux suggests otherwise. Based on feedback, we have decided to make this setting opt-in on Linux and leave the native title bar as the default. + +The custom title bar provides many benefits including great theming support and better accessibility through keyboard navigation and screen readers. Unfortunately, these benefits do not translate as well to the Linux platform. Linux has a variety of desktop environments and window managers that can make the VS Code theming look foreign to users. For users needing the accessibility improvements, we recommend enabling the custom title bar when running in accessibility mode using a screen reader. You can still manually set the title bar with the **Window: Title Bar Style** (`window.titleBarStyle`) setting. + +### Broken cursor in editor with display scaling enabled + +Due to an upstream [issue](https://github.com/electron/electron/issues/14787) with Electron, the mouse cursor may render incorrectly with scaling enabled. If you notice that the usual text cursor is not being rendered inside the editor as you would expect, try falling back to the native menu bar by configuring the setting `window.titleBarStyle` to `native`. + +### Repository changed its origin value + +If you receive an error similar to the following: + +``` +E: Repository '...' changed its 'Origin' value from '...' to '...' +N: This must be accepted explicitly before updates for this repository can be applied. See apt-secure(8) manpage for details. +``` + +Use `apt` instead of `apt-get` and you will be prompted to accept the origin change: + +```bash +sudo apt update +``` diff --git a/docs/setup/mac.md b/docs/setup/mac.md new file mode 100644 index 0000000000000000000000000000000000000000..5acfaed115ac8282ff74f5f4744257cdc7a28b66 --- /dev/null +++ b/docs/setup/mac.md @@ -0,0 +1,77 @@ +--- +Order: 3 +Area: setup +TOCTitle: macOS +ContentId: EEADB50A-F5E3-41E9-89DA-35F165196691 +PageTitle: Running Visual Studio Code on macOS +DateApproved: 3/7/2019 +MetaDescription: Get Visual Studio Code up and running on Mac (macOS). +--- +# Visual Studio Code on macOS + +## Installation + +1. [Download Visual Studio Code](https://go.microsoft.com/fwlink/?LinkID=534106) for macOS. +2. Double-click on the downloaded archive to expand the contents. +3. Drag `Visual Studio Code.app` to the `Applications` folder, making it available in the `Launchpad`. +4. Add VS Code to your Dock by right-clicking on the icon to bring up the context menu and choosing **Options**, **Keep in Dock**. + +## Launching from the command line + +You can also run VS Code from the terminal by typing 'code' after adding it to the path: + +- Launch VS Code. +- Open the **Command Palette** (`kb(workbench.action.showCommands)`) and type 'shell command' to find the **Shell Command: Install 'code' command in PATH** command. + +![macOS shell commands](images/mac/shell-command.png) + +- Restart the terminal for the new `$PATH` value to take effect. You'll be able to type 'code .' in any folder to start editing files in that folder. + +>**Note:** If you still have the old `code` alias in your `.bash_profile` (or equivalent) from an early VS Code version, remove it and replace it by executing the **Shell Command: Install 'code' command in PATH** command. + +To manually add VS Code to your path, you can run the following commands: + +```bash +cat << EOF >> ~/.bash_profile +# Add Visual Studio Code (code) +export PATH="\$PATH:/Applications/Visual Studio Code.app/Contents/Resources/app/bin" +EOF +``` + +Start a new terminal to pick up your `.bash_profile` changes. + +**Note**: The leading slash `\` is required to prevent `$PATH` from expanding during the concatenation. Remove the leading slash if you want to run the export command directly in a terminal. + +## Touch Bar support + +Out of the box VS Code adds actions to navigate in editor history as well as the full Debug tool bar to control the debugger on your Touch Bar: + +![macOS Touch Bar](images/mac/touchbar.gif) + +## Mojave privacy protections + +After upgrading to macOS Mojave version, you may see dialogs saying "Visual Studio Code would like to access your {calendar/contacts/photos}." This is due to the new privacy protections in Mojave and is not specific to VS Code. The same dialogs may be displayed when running other applications as well. The dialog is shown once for each type of personal data and it is fine to choose **Don't Allow** since VS Code does not need access to those folders. You can read a more detailed explanation [here](https://discuss.atom.io/t/why-does-macos-say-that-atom-wants-to-access-my-calendar-contacts-photos-etc). + +## Updates + +VS Code ships monthly [releases](/updates) and supports auto-update when a new release is available. If you're prompted by VS Code, accept the newest update and it will get installed (you won't need to do anything else to get the latest bits). + +>Note: You can [disable auto-update](/docs/supporting/faq.md#how-do-i-opt-out-of-vs-code-autoupdates) if you prefer to update VS Code on your own schedule. + +## Preferences menu + +You can configure VS Code through [settings](/docs/getstarted/settings.md), [color themes](/docs/getstarted/themes.md), and [custom keybindings](/docs/getstarted/keybindings.md) and you will often see mention of the **File** > **Preferences** menu group. On a macOS, the **Preferences** menu group is under **Code**, not **File**. + +## Next steps + +Once you have installed VS Code, these topics will help you learn more about VS Code: + +* [Additional Components](/docs/setup/additional-components.md) - Learn how to install Git, Node.js, TypeScript, and tools like Yeoman. +* [User Interface](/docs/getstarted/userinterface.md) - A quick orientation around VS Code. +* [User/Workspace Settings](/docs/getstarted/settings.md) - Learn how to configure VS Code to your preferences settings. + +## Common questions + +### Why do I see "Visual Studio Code would like access to your calendar." + +If you are running macOS Mojave version, you may see dialogs saying "Visual Studio Code would like to access your {calendar/contacts/photos}." This is due to the new privacy protections in Mojave [discussed above](#mojave-privacy-protections). It is fine to choose **Don't Allow** since VS Code does not need access to those folders. \ No newline at end of file diff --git a/docs/setup/network.md b/docs/setup/network.md new file mode 100644 index 0000000000000000000000000000000000000000..d2a0197a317154180763ea91a1c4072b1b6a7fef --- /dev/null +++ b/docs/setup/network.md @@ -0,0 +1,106 @@ +--- +Order: 5 +Area: setup +TOCTitle: Network +ContentId: 84F36EDE-4D66-4A2E-B4D1-F020C73EB2AD +PageTitle: Setup Visual Studio Code's Network Connection +DateApproved: 3/7/2019 +MetaDescription: Setup VS Code's Network Connection. +--- +# Network Connections in Visual Studio Code + +Visual Studio Code is built on top of [Electron](https://electron.atom.io/) and benefits from all the networking stack capabilities of [Chromium](https://www.chromium.org/). This also means that VS Code users get much of the networking support available in [Google Chrome](https://www.google.com/chrome/index.html). + +## Common hostnames + +A handful of features within VS Code require network communication to work, such as the auto-update mechanism, querying and installing extensions, and telemetry. For these features to work properly in a proxy environment, you must have the product correctly configured. + +If you are behind a firewall which needs to whitelist domains used by VS Code, here's the list of hostnames you should allow communication to go through: + +* `update.code.visualstudio.com` +* `code.visualstudio.com` +* `go.microsoft.com` +* `vscode.blob.core.windows.net` +* `marketplace.visualstudio.com` +* `*.gallerycdn.vsassets.io` +* `rink.hockeyapp.net` +* `vscode.search.windows.net` +* `raw.githubusercontent.com` +* `vsmarketplacebadge.apphb.com` + +## Proxy server support + +VS Code has exactly the same proxy server support as Google Chromium. Here's a snippet from [Chromium's documentation](https://www.chromium.org/developers/design-documents/network-settings): + +``` +"The Chromium network stack uses the system network settings so that users and administrators can control the network settings of all applications easily. The network settings include: + + - proxy settings + - SSL/TLS settings + - certificate revocation check settings + - certificate and private key stores" +``` + +This means that your proxy settings should be picked up automatically. + +Otherwise, you can use the following command line arguments to control your proxy settings: + +```bash +# Disable proxy +--no-proxy-server + +# Manual proxy address +--proxy-server==[:][;...] | [:] | "direct://" + +# Manual PAC address +--proxy-pac-url= + +# Disable proxy per host +--proxy-bypass-list=(|)[:][;...] +``` + +[Click here](https://www.chromium.org/developers/design-documents/network-settings) to know more about these command line arguments. + +### Authenticated proxies + +Authenticated proxies should work seamlessly within VS Code with the addition of [PR #22369](https://github.com/Microsoft/vscode/pull/22369). + +The authentication methods supported are: + +* Basic +* Digest +* NTLM +* Negotiate + +When using VS Code behind an authenticated HTTP proxy, the following authentication popup should appear: + +![proxy](images/network/proxy.png) + +Note that SOCKS5 proxy authentication support isn't implemented yet; you can follow the [issue in Chromium's issue tracker](https://bugs.chromium.org/p/chromium/issues/detail?id=256785). + +[Click here](https://www.chromium.org/developers/design-documents/http-authentication) to read more about HTTP proxy authentication within VS Code. + +### SSL certificates + +Often HTTPS proxies rewrite SSL certificates of the incoming requests. Chromium was designed to reject responses which are signed by certificates which it doesn't trust. If you hit any SSL trust issues, there are a few options available for you: + +* Since Chromium simply uses the OS's certificate trust infrastructure, the preferred option is to add your proxy's certificate to your OS's trust chain. [Click here](https://www.chromium.org/Home/chromium-security/root-ca-policy) to read more about the Root Certificate Policy in Chromium. +* If your proxy runs in `localhost`, you can always try the [`--allow-insecure-localhost`](https://peter.sh/experiments/chromium-command-line-switches/#allow-insecure-localhost) command line flag. +* If all else fails, you can tell VS Code to ignore all certificate errors using the [`--ignore-certificate-errors`](https://peter.sh/experiments/chromium-command-line-switches/#ignore-certificate-errors) command line flag. **Warning:** This is **dangerous** and **not recommended**, since it opens the door to security issues. + +## Legacy proxy server support + +Extensions don't benefit yet from the same proxy support that VS Code supports. You can follow this issue's development in [GitHub](https://github.com/Microsoft/vscode/issues/12588). + +Similarly to extensions, a few other VS Code features don't yet fully support proxy networking, namely the CLI interface. The CLI interface is what you get when running `code --install-extension vscodevim.vim` from a command prompt or terminal. You can follow this issue's development in [GitHub](https://github.com/Microsoft/vscode/issues/29910). + +Due to both of these constraints, the `http.proxy`, `http.proxyStrictSSL` and `http.proxyAuthorization` variables are still part of VS Code's settings, yet they are only respected in these two scenarios. + +## Troubleshooting + +Here are some helpful links that might help you troubleshoot networking issues in VS Code: + +* [Network Settings](https://www.chromium.org/developers/design-documents/network-settings) +* [Debugging problems with the network proxy](https://www.chromium.org/developers/design-documents/network-stack/debugging-net-proxy) +* [Configuring a SOCKS proxy server in Chrome](https://www.chromium.org/developers/design-documents/network-stack/socks-proxy) +* [Proxy settings and fallback (Windows)](https://www.chromium.org/developers/design-documents/network-stack/proxy-settings-fallback) diff --git a/docs/setup/setup-overview.md b/docs/setup/setup-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..c778700f6305babe2041ac4d060811278bd3bb5f --- /dev/null +++ b/docs/setup/setup-overview.md @@ -0,0 +1,85 @@ +--- +Order: 1 +Area: setup +TOCTitle: Overview +ContentId: FC5262F3-D91D-4665-A5D2-BCBCCF66E53A +PageTitle: Setting up Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Get Visual Studio Code up and running. +MetaSocialImage: quicksetup_QuickSetup.png +--- +# Setting up Visual Studio Code + +Getting up and running with Visual Studio Code is quick and easy. It is a small download so you can install in a matter of minutes and give VS Code a try. + +## Cross platform + +VS Code is a free code editor which runs on the macOS, Linux and Windows operating systems. + +Follow the platform specific guides below: + +* [macOS](/docs/setup/mac.md) +* [Linux](/docs/setup/linux.md) +* [Windows](/docs/setup/windows.md) + +VS Code is lightweight and should run on most available hardware and platform versions. You can review the [System Requirements](/docs/supporting/requirements.md) to check if your computer configuration is supported. + +## Update cadence + +VS Code releases a new version [each month](/updates) with new features and important bug fixes. Most platforms support auto updating and you will be prompted to install the new release when it becomes available. You can also manually check for updates by running **Help** > **Check for Updates**. + +>Note: You can [disable auto-update](/docs/supporting/faq.md#how-do-i-opt-out-of-vs-code-autoupdates) if you prefer to update VS Code on your own schedule. + +## Insiders nightly build + +If you'd like to try our nightly builds to see new features early or verify bug fixes, you can install our [Insiders build](/insiders). The Insiders build installs side-by-side with the monthly Stable build and you can freely work with either on the same machine. The Insiders build is the same one the VS Code development team uses on a daily basis and we really appreciate people trying out new features and providing feedback. + +## Additional components + +VS Code is an editor, first and foremost, and prides itself on a small footprint. Unlike traditional IDEs which tend to include everything but the kitchen sink, you can tune your installation to the development technologies you care about. Be sure to read the [Additional Components](/docs/setup/additional-components.md) topic after reading the platform guides to learn about customizing your VS Code installation. + +## Extensions + +VS Code [extensions](/docs/editor/extension-gallery.md) let third parties add support for additional: + +* Languages - [C++](/docs/languages/cpp.md), [C#](/docs/languages/csharp.md), [Go](/docs/languages/go.md), [Java](/docs/languages/java.md), [Python](/docs/languages/python.md) +* Tools - [ESLint](https://marketplace.visualstudio.com/items/dbaeumer.vscode-eslint), [JSHint](https://marketplace.visualstudio.com/items/dbaeumer.jshint) , [PowerShell](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell) +* Debuggers - [Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome), [PHP XDebug](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug). +* Keymaps - [Vim](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim), [Sublime Text](https://marketplace.visualstudio.com/items?itemName=ms-vscode.sublime-keybindings), [IntelliJ](https://marketplace.visualstudio.com/items?itemName=k--kato.intellij-idea-keybindings), [Emacs](https://marketplace.visualstudio.com/items?itemName=hiro-sun.vscode-emacs), [Atom](https://marketplace.visualstudio.com/items?itemName=ms-vscode.atom-keybindings), [Visual Studio](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vs-keybindings), [Eclipse](https://marketplace.visualstudio.com/items?itemName=alphabotsec.vscode-eclipse-keybindings) + +Extensions integrate into VS Code's UI, commands, and task running systems so you'll find it easy to work with different technologies through VS Code's shared interface. Check out the VS Code extension [Marketplace](https://marketplace.visualstudio.com/vscode) to see what's available. + +## Next steps + +Once you have installed and set up VS Code, these topics will help you learn more about VS Code: + +* [Additional Components](/docs/setup/additional-components.md) - Learn how to install Git, Node.js, TypeScript and tools like Yeoman. +* [User Interface](/docs/getstarted/userinterface.md) - A quick orientation to VS Code. +* [Basic Editing](/docs/editor/codebasics.md) - Learn about the powerful VS Code editor. +* [Code Navigation](/docs/editor/editingevolved.md) - Move quickly through your source code. +* [Debugging](/docs/editor/debugging.md) - Debug your source code directly in the VS Code editor. +* [Proxy Server Support](/docs/setup/network.md) - Configure your proxy settings. + +If you'd like to get something running quickly, try the [Node.js tutorial](/docs/nodejs/nodejs-tutorial.md) walkthrough which will have you debugging a Node.js web application with VS Code in minutes. + +## Common questions + +### What are the system requirements for VS Code? + +We have a list of [System Requirements](/docs/supporting/requirements.md). + +### How big is VS Code? + +VS Code is a small download (< 100 MB) and has a disk footprint of less than 200 MB, so you can quickly install VS Code and try it out. + +### How do I create and run a new project? + +VS Code doesn't include a traditional **File** > **New Project** dialog or pre-installed project templates. You'll need to add [additional components](/docs/setup/additional-components.md) and scaffolders depending on your development interests. With scaffolding tools like [Yeoman](http://yeoman.io/) and the multitude of modules available through the [npm](https://www.npmjs.com/) package manager, you're sure to find appropriate templates and tools to create your projects. + +### How do I know which version I'm running? + +On Linux and Windows, choose **Help** > **About**. On macOS, use **Code** > **About Visual Studio Code**. + +### Why is VS Code saying my installation is Unsupported? + +VS Code has detected that some installation files have been modified, perhaps by an extension. Reinstalling VS Code will replace the affected files. See our [FAQ topic](/docs/supporting/faq.md#installation-appears-to-be-corrupt-unsupported) for more details. diff --git a/docs/setup/windows.md b/docs/setup/windows.md new file mode 100644 index 0000000000000000000000000000000000000000..51c687c19011f11336d7877781fa1a1de198cc85 --- /dev/null +++ b/docs/setup/windows.md @@ -0,0 +1,79 @@ +--- +Order: 4 +Area: setup +TOCTitle: Windows +ContentId: 4670C281-5761-46E6-8C46-10D523946FFB +PageTitle: Running Visual Studio Code on Windows +DateApproved: 3/7/2019 +MetaDescription: Get Visual Studio Code up and running on Windows +--- +# Visual Studio Code on Windows + +## Installation + +1. Download the [Visual Studio Code installer](https://go.microsoft.com/fwlink/?LinkID=534107) for Windows. +2. Once it is downloaded, run the installer (VSCodeUserSetup-{version}.exe). This will only take a minute. +3. By default, VS Code is installed under `C:\users\{username}\AppData\Local\Programs\Microsoft VS Code`. + +Alternatively, you can also download a [Zip archive](/docs/?dv=winzip), extract it and run Code from there. + +>**Note:** .NET Framework 4.5.2 or higher is required for VS Code. If you are using Windows 7, make sure you have at least [.NET Framework 4.5.2](https://www.microsoft.com/download/details.aspx?id=42643) installed. + +>**Tip:** Setup will add Visual Studio Code to your `%PATH%`, so from the console you can type 'code .' to open VS Code on that folder. You will need to restart your console after the installation for the change to the `%PATH%` environmental variable to take effect. + +## 32 bit versions + +If you need to run a 32 bit version of VS Code, both a 32 bit [Installer](https://go.microsoft.com/fwlink/?LinkId=723965) and [Zip archive](https://go.microsoft.com/fwlink/?LinkID=733265) are available. + +## Updates + +VS Code ships monthly [releases](/updates) and supports auto-update when a new release is available. If you're prompted by VS Code, accept the newest update and it will be installed (you won't need to do anything else to get the latest bits). + +>Note: You can [disable auto-update](/docs/supporting/faq.md#how-do-i-opt-out-of-vs-code-autoupdates) if you prefer to update VS Code on your own schedule. + +## Next steps + +Once you have installed VS Code, these topics will help you learn more about VS Code: + +* [Additional Components](/docs/setup/additional-components.md) - Learn how to install Git, Node.js, TypeScript and tools like Yeoman. +* [User Interface](/docs/getstarted/userinterface.md) - A quick orientation to VS Code. +* [User/Workspace Settings](/docs/getstarted/settings.md) - Learn how to configure VS Code to your preferences through settings. +* [Tips and Tricks](/docs/getstarted/tips-and-tricks.md) - Lets you jump right in and learn how to be productive with VS Code. + +## Common questions + +### What command line arguments are supported by the Windows Setup? + +VS Code uses [Inno Setup](http://www.jrsoftware.org/isinfo.php) to create its setup package +for Windows. Thus, all the [Inno Setup command line switches](http://www.jrsoftware.org/ishelp/index.php?topic=setupcmdline) are available for use. + +Additionally, you can prevent the Setup from launching VS Code after completion with `/mergetasks=!runcode`. + +### Scrolling is laggy and not smooth + +On certain devices, editor scrolling is not smooth but laggy for an unpleasant experience. If you notice this issue, make sure you install the Windows 10 October 2018 update where this issue is fixed. + +### I'm having trouble with the installer + +Try using the [zip file](/docs/?dv=winzip) instead of the installer. To use this, unzip VS Code in your `AppData\Local\Programs` folder. + +>**Note:** When VS Code is installed via a Zip file, you will need to manually update it for each [release](/updates). + +### Icons are missing + +I installed Visual Studio Code on my Windows 7 or 8 machine. Why are some icons not appearing in the workbench and editor? + +VS Code uses [SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) icons and we have found instances where the .SVG file extension is associated with something other than `image/svg+xml`. We're considering options to fix it, but for now here's a workaround: + +Using the Command Prompt: + +1. Open an Administrator Command Prompt. +2. Type `REG ADD HKCR\.svg /f /v "Content Type" /t REG_SZ /d image/svg+xml`. + +Using the Registry Editor (regedit): + +1. Start `regedit`. +2. Open the `HKEY_CLASSES_ROOT` key. +3. Find the `.svg` key. +4. Set its `Content Type` Data value to `image/svg+xml`. +5. Exit `regedit`. diff --git a/docs/supporting/errors.md b/docs/supporting/errors.md new file mode 100644 index 0000000000000000000000000000000000000000..76dbf4335c96527b0747cc2ef42690f54603bc55 --- /dev/null +++ b/docs/supporting/errors.md @@ -0,0 +1,80 @@ +--- +Order: +TOCTitle: Error Codes +ContentId: 343B5C4D-3473-4454-AD22-084F405D6905 +PageTitle: Visual Studio Code workarounds for errors you might hit in the product. +DateApproved: 3/7/2019 +MetaDescription: Several error conditions can easily be resolved by the user this page is designed to help un-block you. +--- +# Common Error Cases + +Some errors that occur when using Visual Studio Code can be worked around or resolved by you. This topic describes several common error conditions, listed by error code number, and what you can do to resolve them. + +## 20002 + +**Error:** Cannot find '/usr/bin/gnome-terminal' for launching your Node.js program + +On Linux, the VS Code Node.js debugger requires the [gnome-terminal](https://help.gnome.org/users/gnome-terminal/stable/) emulator for launching the Node.js program. If gnome-terminal is not installed, the VS Code debugger cannot launch your program for debugging. + +There are two options for solving this problem: + +* Install the gnome-terminal by running the command `sudo apt-get install gnome-terminal` (or the equivalent of your Linux distribution). +* Manually launch your program in debug mode by passing a `--inspect` or `--inspect-brk` option to Node.js and then attach the VS Code debugger to port 9229 on 'localhost'. + +## 20003 + +**Error:** Attribute 'program' is not absolute; consider adding '${workspaceFolder}/' as a prefix to make it absolute. + +This error occurs when you have a relative path in your [debug configuration](/docs/editor/debugging.md#launch-configurations) `launch.json` file (located in your workspace `.vscode` directory). + +In the example below, the `program` attribute has a relative path to `app.js` at the root of the workspace (project folder). + +```json +{ +"version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "./app.js" + } + ] +} +``` + +The fix is to use an absolute path or better use the `${workspaceFolder}` variable which will resolve to the absolute path of the project folder. + +```json +{ +"version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${workspaceFolder}/app.js" + } + ] +} +``` + +By using the `${workspaceFolder}` variable, you won't need to update the absolute path if the project is moved or shared with other developers. + +In previous versions of VS Code, you were allowed to use relative paths in your launch configurations but this was problematic. VS Code now warns you about relative paths when you start a debugging session and recommends prefixing the relative path with `${workspaceFolder}/`. VS Code also checks other path attributes, such as `cwd` (current working directory), `outFiles` (location of other JavaScript files), and `runtimeExecutable`. + +> **Tip:** See the VS Code [debugging](/docs/editor/debugging.md) documentation for more information about `launch.json`, [debugger configuration](/docs/editor/debugging.md#launch-configurations), and [variable substitution](/docs/editor/variables-reference.md). + +## Didn't find a solution? + +### GitHub issues + +If the steps above don't help you, you may have hit a bug. You can check our [reported issues](https://github.com/microsoft/vscode/issues) to see if others have reported the same issue. + +### Online search + +You can also search the rest of our online [documentation](/docs) for answers in our main topics and **Common questions** sections. The online **Search** control is located in the upper right of the [code.visualstudio.com](/docs) website. + +### Stack Overflow + +There is also an active VS Code [Stack Overflow channel](https://go.microsoft.com/fwlink/?LinkID=536384) where you can browse answers or ask a question. diff --git a/docs/supporting/faq.md b/docs/supporting/faq.md new file mode 100644 index 0000000000000000000000000000000000000000..7ce779370737656c6d05cbeb89e61ad9540c3904 --- /dev/null +++ b/docs/supporting/faq.md @@ -0,0 +1,206 @@ +--- +TOCTitle: FAQ +ContentId: E02F97FD-842B-4D27-B461-37DD18B2582E +PageTitle: Visual Studio Code Frequently Asked Questions +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code Frequently Asked Questions +--- +# Visual Studio Code FAQ + +Our docs contain a **Common questions** section as needed for specific topics. We've captured items here that don't fit in the other topics. + +If you don't see an answer to your question here, check our previously [reported issues](https://github.com/microsoft/vscode/issues) and our [Updates](/updates) notes. + +## What is the difference between VS Code and VS Community? + +Visual Studio Code is a streamlined code editor with support for development operations like debugging, task running and version control. It aims to provide just the tools a developer needs for a quick code-build-debug cycle and leaves more complex workflows to fuller featured IDEs. + +## Which OS's are supported? + +VS Code runs on macOS, Linux, and Windows. See [Requirements](requirements) for the supported versions. You can find more platform specific details under [SETUP](/docs/setup/setup-overview.md). + +## Is VS Code free? + +Yes, VS Code is [free for private or commercial use](https://code.visualstudio.com/license). + +## Report an issue with a VS Code extension + +For bugs, feature requests or to contact an extension author, you should use the links available in the Visual Studio Code [Marketplace](https://marketplace.visualstudio.com/vscode) or use **Help: Report Issue** from the Command Palette. However, if there is an issue where an extension does not follow our code of conduct, for example it includes profanity, pornography or presents a risk to the user, then we have an email alias where you can [contact us to report the issue](mailto:VSMarketplace@microsoft.com). Once the mail is received, our Marketplace team will look into an appropriate course of action, up to and including unpublishing the extension. + +## How do I find the VS Code version? + +You can find the VS Code version information in the About dialog box. + +On macOS, go to **Code** > **About Visual Studio Code**. + +On Windows and Linux, go to **Help** > **About**. + +The VS Code version is the first **Version** number listed and has the version format 'major.minor.release', for example '1.27.0'. + +## How do I opt out of VS Code auto-updates? + +By default, VS Code is set up to auto-update for macOS and Windows users when we release new updates. If you do not want to get automatic updates, you can set the **Update: Mode** setting from `default` to `none`. + +To modify the update mode, go to **File** > **Preferences** > **Settings** (macOS: **Code** > **Preferences** > **Settings**), search for `update mode` and change the setting to `none`. + +If you use the JSON editor for your settings, add the following line: + +```json + "update.mode": "none" +``` + +You can install a previous release of VS Code by uninstalling your current version and then installing the download provided at the top of a specific release page under [Updates](/updates). + +>**Note:** On Linux: If the VS Code repository was installed correctly then your system package manager should handle auto-updating in the same way as other packages on the system. See [Installing VS Code on Linux](/docs/setup/linux.md#updates). + +## Can I run a portable version of VS Code? + +Yes, VS Code has a [Portable Mode](/docs/editor/portable.md) which lets you keep settings and data in the same location as your installation, for example, on a USB drive. + +## Licensing + +### Location + +You can find the VS Code licenses, third party notices and [Chromium](https://www.chromium.org) Open Source credit list under your VS Code installation location `resources\app` folder. VS Code's `ThirdPartyNotices.txt`, Chromium's `Credits_*.html`, and VS Code's English language `LICENSE.txt` are available under `resources\app`. Localized versions of `LICENSE.txt` by Language ID are under `resources\app\licenses`. + +### Why does Visual Studio Code have a different license than the vscode GitHub repository? + +To learn why Visual Studio Code, the product, has a different license than vscode, the open source [GitHub repository](https://github.com/microsoft/vscode), see [issue #60](https://github.com/Microsoft/vscode/issues/60#issuecomment-161792005) for a detailed explanation. + +## Can I run prerelease versions of VS Code? + +Want an early peek at new VS Code features? You can try prerelease versions of VS Code by installing the "Insiders" build. The Insiders build installs side by side to your stable VS Code install and has isolated settings, configurations and extensions. The Insiders build is updated nightly so you'll get the latest bug fixes and feature updates from the day before. + +To install the Insiders build, go to the Insiders [download page](/insiders). + +## VS Code gets unresponsive right after opening a folder + +When you open a folder, VS Code will search for typical project files to offer you additional tooling (e.g. the solution picker in the status bar to open a solution). If you open a folder with lots of files, the search can take a large amount of time and CPU resources during which VS Code might be slow to respond. We plan to improve this in the future but for now you can exclude folders from the explorer via the `files.exclude` setting and they will not be searched for project files: + +```json + "files.exclude": { + "**/largeFolder": true + } +``` + +## VS Code is blank? + +The Electron shell used by Visual Studio Code has trouble with some GPU (graphics processing unit) hardware acceleration. If VS Code is displaying a blank (empty) main window, you can try disabling GPU acceleration when launching VS Code by adding the Electron `--disable-gpu` command line switch. + +```bash +code --disable-gpu +``` + +## Blurriness on macOS Mojave + +If you have updated to macOS 10.14 (Mojave), you might have noticed that fonts in VS Code look blurry if you are not using a high-DPI monitor. + +A workaround for this is to run: + +```bash +defaults write com.microsoft.VSCode.helper CGFontRenderingFontSmoothingDisabled -bool NO +``` + +from a terminal followed by restarting your computer. + +Note that this change is global for every application and not specific to VS Code. See [issue 51132](https://github.com/Microsoft/vscode/issues/51132) for the related discussion. + +## Installation appears to be corrupt [Unsupported] + +VS Code does a background check to detect if the installation has been changed on disk and if so, you will see the text '[Unsupported]' in the title bar. This is done since some extensions directly modify (patch) the VS Code product in such a way that is semi-permanent (until the next update) and this can cause hard to reproduce issues. We are not trying to block VS Code patching, but we want to raise awareness that patching VS Code means you are running an unsupported version. Reinstalling VS Code will replace the modified files and silence the warning. + +## GDPR and VS Code + +As the General Data Protection Regulation comes into effect, we want to take this opportunity to reiterate that we take privacy very seriously. That's both for Microsoft as a company and specifically within the VS Code team. + +VS Code does collect telemetry data which we use to help understand how to improve the product. For example, it helps debug issues such as slow start-up times and prioritize features. While we appreciate this insight, we also know that not everyone wants to send this data, so we continue to offer the ability to disable telemetry as outlined [here](https://code.visualstudio.com/docs/supporting/faq#_how-to-disable-telemetry-reporting). + +In preparation for GDPR, we have made several updates to VS Code, these include: + +* Making it easier to opt out of telemetry collection by placing a notification in product for all existing and new users. +* Reviewing and classifying the telemetry that we send (which is documented in [our OSS codebase](https://github.com/Microsoft/vscode/pull/34997)). +* Ensuring that we have valid data retention policies in place for any data we do collect, for example crash dumps. + +In short, we have worked hard to do the right thing, for all users, as these practices apply to all geographies, not just Europe. + +One question we expect people to ask is to see the data we collect. However, we don't have a reliable way to do this as VS Code does not have is a 'sign-in' experience that would uniquely identify a user. We do send information which helps us approximate a single user for diagnostic purposes (this is based on a hash of the network adapter NIC) but this is not guaranteed to be unique. For example, VM's often rotate NIC ID's or allocate from a pool. This technique is sufficient to help us when working through problems, but it is not reliable enough for us to 'provide your data'. + +In conclusion, we expect our approach to evolve as we learn more about GDPR and the expectations of our users. We greatly appreciate the data users do send to us, as it is very valuable, VS Code is a better product for everyone because it. And again, if you are worried about privacy, we offer the ability to disable sending telemetry as described [here](https://code.visualstudio.com/docs/supporting/faq#_how-to-disable-telemetry-reporting). + +You can find more information about how the Visual Studio family approaches GDPR at [Visual Studio Family Data Subject Requests for the GDPR](https://docs.microsoft.com/microsoft-365/compliance/gdpr-dsr-visual-studio-family). + +## How to disable telemetry reporting + +VS Code collects usage data and sends it to Microsoft to help improve our products and services. Read our [privacy statement](https://go.microsoft.com/fwlink/?LinkID=528096&clcid=0x409) to learn more. + +If you don't wish to send usage data to Microsoft, you can set the `telemetry.enableTelemetry` setting to `false`. + +From **File** > **Preferences** > **Settings** (macOS: **Code** > **Preferences** > **Settings**), search for `telemetry.enableTelemetry` and uncheck the setting. This will silence all telemetry events from VS Code going forward. Telemetry information may have been collected and sent up until the point when you disable the setting. + +If you use the JSON editor for your settings, add the following line: + +```json + "telemetry.enableTelemetry": false +``` + +You can inspect telemetry events in the Output panel by setting the log level to **Trace** using **Developer: Set Log Level** from the Command Palette. + +> **Important Notice**: VS Code gives you the option to install Microsoft and third party extensions. These extensions may be collecting their own usage data and are not controlled by the `telemetry.enableTelemetry` setting. Consult the specific extension's documentation to learn about its telemetry reporting. + +## How to disable crash reporting + +VS Code collects data about any crashes that occur and sends it to Microsoft to help improve our products and services. Read our [privacy statement](https://go.microsoft.com/fwlink/?LinkID=528096&clcid=0x409) to learn more. + +If you don't wish to send crash data to Microsoft, you can set the `telemetry.enableCrashReporter` setting to `false`. + +From **File** > **Preferences** > **Settings** (macOS: **Code** > **Preferences** > **Settings**), search for `telemetry.enableCrashReporter` and uncheck the setting. + +If you use the JSON editor for your settings, add the following line: + +```json + "telemetry.enableCrashReporter": false +``` + +> **Important Notice**: This option requires a restart of VS Code to take effect. + +## Managing online services + +Beyond crash reporting and telemetry, VS Code uses online services for various other purposes such as downloading product updates, finding, installing and updating extensions, or providing Natural Language Search within Settings. You can choose to turn on/off features that use these services. + +Please note, that turning off these features does not put VS Code into offline mode. If, for example, you search for extensions in the **Extensions** view, VS Code still searches the online VS Code Marketplace. The settings ensure that VS Code does not talk to online services without you requesting it. + +From **File** > **Preferences** > **Settings** (macOS: **Code** > **Preferences** > **Settings**), and search for `@tag:usesOnlineServices`. This will display all settings that control the usage of online services and you can individually switch them on or off. + +> **Important Notice**: VS Code gives you the option to install Microsoft and third party extensions. These extensions may also use online services and may not provide settings to configure the usage of these online services, or they may not register their settings to show up when searching for `@tag:usesOnlineServices`. Consult the specific extension's documentation to learn about its usage of online services. + +## What non-Microsoft online services does VS Code talk to + +The built-in **npm support for VS Code** extension sends requests to `https://registry.npmjs.org` and `https://registry.bower.io`. + +The built-in **TypeScript and JavaScript Language Features** extension queries the `@types` domain at `https://registry.npmjs.org`. + +When you use **Developer: Toggle Developer Tools** or **Developer: Open Webview Developer Tools**, VS Code may talk to Google servers to fetch data needed to launch Developer Tools. + +## Do you send all my information to a recommendation service? + +VS Code provides extension recommendations based on your file types, your workspace, and your environment. File type recommendations are either precomputed or dynamic. Workspace and environment recommendations are always precomputed. + +If you want to know why an extension is being recommended, open the extension's detail page. You can find the recommendation reason in the page header. + +### Dynamic recommendations + +When you open a file type for which VS Code does not have any precomputed recommendation, it asks the extension Marketplace for extensions that declare that they support this file type. If the query returns extensions you don't have installed, VS Code tells you about it. + +### Precomputed recommendations + +VS Code collects telemetry about which extensions are being activated for what file types and what workspaces/folders. We identify folders by computing a hash of each of the folder's Git remotes. + +We use this information to precompute anonymous recommendations. Precomputed recommendations are instructions that spell out under which conditions an extension should be recommended. For example, when we see an interesting co-relation between two extensions A and B, one instruction might be: Recommend extension B if the user has installed extension A but not B. + +Some precomputed recommendations are shipped as part of the product while additional precomputed recommendations are fetched at runtime from an online Microsoft service. VS Code independently evaluates and executes precomputed recommendations without sending any user information to any online service. + +## Technical Support + +You can ask questions and search for answers on [Stack Overflow](https://stackoverflow.com/questions/tagged/vscode) and enter issues and feature requests directly in our [GitHub repository](https://github.com/Microsoft/vscode/blob/master/CONTRIBUTING.md). + +If you'd like to contact a professional support engineer, you can open a ticket with the [Microsoft assisted support team](https://support.microsoft.com/assistedsupportproducts). diff --git a/docs/supporting/requirements.md b/docs/supporting/requirements.md new file mode 100644 index 0000000000000000000000000000000000000000..d6a868a3e2233a34729a0d25363d697454b8447d --- /dev/null +++ b/docs/supporting/requirements.md @@ -0,0 +1,38 @@ +--- +Order: +TOCTitle: Requirements +ContentId: 1D4850EE-85E2-4152-81BE-FECAE62EA99E +PageTitle: Requirements for Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Visual Studio Code hardware and platform (operating system) requirements. +--- +# Requirements for Visual Studio Code + +## Hardware + +Visual Studio Code is a small download (< 100 MB) and has a disk footprint of 200 MB. VS Code is lightweight and should easily run on today's hardware. + +We recommend: + +* 1.6 GHz or faster processor +* 1 GB of RAM + +## Platforms + +VS Code has been tested on the following platforms: + +* OS X Yosemite +* Windows 7 (with .NET Framework 4.5.2), 8.0, 8.1 and 10 (32-bit and 64-bit) +* Linux (Debian): Ubuntu Desktop 14.04, Debian 7 +* Linux (Red Hat): Red Hat Enterprise Linux 7, CentOS 7, Fedora 23 + +### Additional Windows requirements + +.NET Framework 4.5.2 is required for VS Code. If you are using Windows 7, please make sure [.NET Framework 4.5.2](https://www.microsoft.com/download/details.aspx?id=42643) is installed. + +### Additional Linux requirements + +* GLIBCXX version 3.4.15 or later +* GLIBC version 2.15 or later + +For a list of currently known issues, see our [FAQ](faq). diff --git a/docs/typescript/images/compiling/build-hello-world.png b/docs/typescript/images/compiling/build-hello-world.png new file mode 100644 index 0000000000000000000000000000000000000000..7eb28ba0cd6e61851ca9a85234b9180cff7e0874 Binary files /dev/null and b/docs/typescript/images/compiling/build-hello-world.png differ diff --git a/docs/typescript/images/compiling/error-status-bar.png b/docs/typescript/images/compiling/error-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..98a8ae208f5751212f44ca49310fd4a5d12fd036 Binary files /dev/null and b/docs/typescript/images/compiling/error-status-bar.png differ diff --git a/docs/typescript/images/compiling/hidingDerivedAfter.png b/docs/typescript/images/compiling/hidingDerivedAfter.png new file mode 100644 index 0000000000000000000000000000000000000000..604ca2813619522d07ce30e30d2f6dfdca886eff Binary files /dev/null and b/docs/typescript/images/compiling/hidingDerivedAfter.png differ diff --git a/docs/typescript/images/compiling/hidingDerivedBefore.png b/docs/typescript/images/compiling/hidingDerivedBefore.png new file mode 100644 index 0000000000000000000000000000000000000000..7870d550bda53935bd0a42058baa142c60ff0594 Binary files /dev/null and b/docs/typescript/images/compiling/hidingDerivedBefore.png differ diff --git a/docs/typescript/images/compiling/select-ts-version-message.png b/docs/typescript/images/compiling/select-ts-version-message.png new file mode 100644 index 0000000000000000000000000000000000000000..360262a45c439968641b9629786d4444971e1875 Binary files /dev/null and b/docs/typescript/images/compiling/select-ts-version-message.png differ diff --git a/docs/typescript/images/compiling/status-bar-version.png b/docs/typescript/images/compiling/status-bar-version.png new file mode 100644 index 0000000000000000000000000000000000000000..be5f5247d66488a5f8f5f3363ffa0f3d7e55cc37 Binary files /dev/null and b/docs/typescript/images/compiling/status-bar-version.png differ diff --git a/docs/typescript/images/compiling/tsconfigintellisense.png b/docs/typescript/images/compiling/tsconfigintellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..f671059dd1b311e9087f2bf501f31552c29bdadc Binary files /dev/null and b/docs/typescript/images/compiling/tsconfigintellisense.png differ diff --git a/docs/typescript/images/compiling/typescript-build.png b/docs/typescript/images/compiling/typescript-build.png new file mode 100644 index 0000000000000000000000000000000000000000..92ac8ca073502ede0156ab75d413c9ef5bd66af8 Binary files /dev/null and b/docs/typescript/images/compiling/typescript-build.png differ diff --git a/docs/typescript/images/compiling/version-status-bar.png b/docs/typescript/images/compiling/version-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..3370608ddb76011c172cd2b6f582ea0c86172e66 Binary files /dev/null and b/docs/typescript/images/compiling/version-status-bar.png differ diff --git a/docs/typescript/images/debugging/client-side-debug-breakpoint.png b/docs/typescript/images/debugging/client-side-debug-breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..6771365f79526125a6bc2a708846cb70a5affe3d Binary files /dev/null and b/docs/typescript/images/debugging/client-side-debug-breakpoint.png differ diff --git a/docs/typescript/images/debugging/configure-debugging.png b/docs/typescript/images/debugging/configure-debugging.png new file mode 100644 index 0000000000000000000000000000000000000000..dc8f0279906097229444870b0d4f9aedec7fc712 Binary files /dev/null and b/docs/typescript/images/debugging/configure-debugging.png differ diff --git a/docs/typescript/images/debugging/debugger-for-chrome.png b/docs/typescript/images/debugging/debugger-for-chrome.png new file mode 100644 index 0000000000000000000000000000000000000000..9b054a83d444ec5ec70b5e9398e16ef8aa6f953e Binary files /dev/null and b/docs/typescript/images/debugging/debugger-for-chrome.png differ diff --git a/docs/typescript/images/debugging/launch-json-intellisense.png b/docs/typescript/images/debugging/launch-json-intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..42d4d13735d57cc9ececb50d0b97e25f859e4f02 Binary files /dev/null and b/docs/typescript/images/debugging/launch-json-intellisense.png differ diff --git a/docs/typescript/images/tutorial/compiled-hello-world.png b/docs/typescript/images/tutorial/compiled-hello-world.png new file mode 100644 index 0000000000000000000000000000000000000000..c110e6a701fba271f76826d426d6ff97e73e26d2 Binary files /dev/null and b/docs/typescript/images/tutorial/compiled-hello-world.png differ diff --git a/docs/typescript/images/tutorial/create-new-file.png b/docs/typescript/images/tutorial/create-new-file.png new file mode 100644 index 0000000000000000000000000000000000000000..ea165a7dfcc4a4aa62a53f74f46bdd56ee5ac084 Binary files /dev/null and b/docs/typescript/images/tutorial/create-new-file.png differ diff --git a/docs/typescript/images/tutorial/debug-breakpoint.png b/docs/typescript/images/tutorial/debug-breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..10c4a4e2407375ebd69a69df62c0826c6c1808d3 Binary files /dev/null and b/docs/typescript/images/tutorial/debug-breakpoint.png differ diff --git a/docs/typescript/images/tutorial/debug-console.png b/docs/typescript/images/tutorial/debug-console.png new file mode 100644 index 0000000000000000000000000000000000000000..b53026c60629f452abf7db7a0aacb2c4c3494592 Binary files /dev/null and b/docs/typescript/images/tutorial/debug-console.png differ diff --git a/docs/typescript/images/tutorial/incorrect-type-error.png b/docs/typescript/images/tutorial/incorrect-type-error.png new file mode 100644 index 0000000000000000000000000000000000000000..c97ccb0276a6553df207c9fb5cd589deba0e0b0c Binary files /dev/null and b/docs/typescript/images/tutorial/incorrect-type-error.png differ diff --git a/docs/typescript/images/tutorial/intellisense.png b/docs/typescript/images/tutorial/intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..1f4dcfef68bb7dde365941f97f124b32e56c2715 Binary files /dev/null and b/docs/typescript/images/tutorial/intellisense.png differ diff --git a/docs/typescript/images/tutorial/parameter-help.png b/docs/typescript/images/tutorial/parameter-help.png new file mode 100644 index 0000000000000000000000000000000000000000..643891ec99e68ff307e3d17f8c9ace49990143ee Binary files /dev/null and b/docs/typescript/images/tutorial/parameter-help.png differ diff --git a/docs/typescript/images/tutorial/run-hello-world.png b/docs/typescript/images/tutorial/run-hello-world.png new file mode 100644 index 0000000000000000000000000000000000000000..26882d4fe5ce8ee98efcf5b5cd2c4b67e63b2376 Binary files /dev/null and b/docs/typescript/images/tutorial/run-hello-world.png differ diff --git a/docs/typescript/images/tutorial/tsconfig-intellisense.png b/docs/typescript/images/tutorial/tsconfig-intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..b24b46cced12330d7ecac6d0d7f62c7ee7e7208b Binary files /dev/null and b/docs/typescript/images/tutorial/tsconfig-intellisense.png differ diff --git a/docs/typescript/images/tutorial/unreachable-code-detected.png b/docs/typescript/images/tutorial/unreachable-code-detected.png new file mode 100644 index 0000000000000000000000000000000000000000..addcb330ef9ca26aabad0ecb3d65a4eeecec31bb Binary files /dev/null and b/docs/typescript/images/tutorial/unreachable-code-detected.png differ diff --git a/docs/typescript/typescript-compiling.md b/docs/typescript/typescript-compiling.md new file mode 100644 index 0000000000000000000000000000000000000000..96c2cc154fa1e36dc0c04c8133cf95e7d2bcd610 --- /dev/null +++ b/docs/typescript/typescript-compiling.md @@ -0,0 +1,254 @@ +--- +Order: 3 +Area: typescript +TOCTitle: Compiling +ContentId: 59543856-da91-4a0d-9a98-9d5f2bf70c71 +PageTitle: TypeScript Compiling with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: Learn about TypeScript compiling with Visual Studio Code. +--- +# Compiling TypeScript + +[TypeScript](https://www.typescriptlang.org) is a typed superset of JavaScript that compiles to plain JavaScript. It offers classes, modules, and interfaces to help you build robust components. The TypeScript language specification can be found [here](https://github.com/Microsoft/TypeScript/tree/master/doc). + +## Install the TypeScript compiler + +Visual Studio Code includes TypeScript language support but does not include the TypeScript compiler, `tsc`. You will need to install the TypeScript compiler either globally or in your workspace to transpile TypeScript source code to JavaScript (`tsc HelloWorld.ts`). + +The easiest way to install TypeScript is through npm, the [Node.js Package Manager](https://www.npmjs.com/). If you have npm installed, you can install TypeScript globally (`-g`) on your computer by: + +```bash +npm install -g typescript +``` + +You can test your install by checking the version or help. + +```bash +tsc --version +tsc --help +``` + +Another option is to install the TypeScript compiler locally in your project (`npm install --save-dev typescript`) and has the benefit of avoiding possible interactions with other TypeScript projects you may have. + +### Compiler versus language service + +It is important to keep in mind that VS Code's TypeScript language service is separate from your installed TypeScript compiler. You can see the VS Code's TypeScript version in the Status Bar when you open a TypeScript file. + +![TypeScript version displayed in the Status Bar](images/compiling/version-status-bar.png) + +Later in the article, we'll discuss how you can [change](#using-newer-typescript-versions) the version of TypeScript language service that VS Code uses. + +## tsconfig.json + +Typically the first step in any new TypeScript project is to add in a `tsconfig.json` file. This defines the TypeScript [project settings](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) such as the compiler options and the files that should be included. To do this, open up the folder where you want to store your source and add in a new file named `tsconfig.json`. Once in this file, IntelliSense (`kb(editor.action.triggerSuggest)`) will help you along the way. + +![tsconfig.json IntelliSense](images/compiling/tsconfigintellisense.png) + +A simple `tsconfig.json` looks like this for ES5, **CommonJS** [modules](http://www.commonjs.org/specs/modules/1.0) and source maps: + +```json +{ + "compilerOptions": { + "target": "es5", + "module": "commonjs", + "sourceMap": true + } +} +``` + +Now when you create a `.ts` file as part of the project we will offer up rich editing experiences and syntax validation. + +## Transpile TypeScript into JavaScript + +VS Code integrates with `tsc` through our integrated [task runner](/docs/editor/tasks.md). We can use this to transpile `.ts` files into `.js` files. Another benefit of using VS Code tasks is that you get integrated error and warning detection displayed in the [Problems](/docs/editor/editingevolved.md#errors-warnings) panel. Let's walk through transpiling a simple TypeScript Hello World program. + +### Step 1: Create a simple TS file + +Open VS Code on an empty folder and create a `helloworld.ts` file, place the following code in that file... + +```typescript +let message : string = "Hello World"; +console.log(message); +``` + +To test that you have the TypeScript compiler `tsc` installed correctly and a working Hello World program, open a terminal and type `tsc helloworld.ts`. You can use the Integrated Terminal (`kb(workbench.action.terminal.toggleTerminal)`) directly in VS Code. + +You should now see the transpiled `helloworld.js` JavaScript file which you can run if you have [Node.js](https://nodejs.org) installed, by typing `node helloworld.js`. + +![build and run Hello World](images/compiling/build-hello-world.png) + +### Step 2: Run the TypeScript build + +Execute **Run Build Task** (`kb(workbench.action.tasks.build)`) from the global **Terminal** menu. If you created a `tsconfig.json` file in the earlier section, this should present the following picker: + +![TypeScript Build](images/compiling/typescript-build.png) + +Select the **tsc: build** entry. This will produce a `HelloWorld.js` and `HelloWorld.js.map` file in the workspace. + +If you selected **tsc: watch**, the TypeScript compiler watches for changes to your TypeScript files and runs the transpiler on each change. + +Under the covers, we run the TypeScript compiler as a task. The command we use is: `tsc -p .` + +### Step 3: Make the TypeScript Build the default + +You can also define the TypeScript build task as the default build task so that it is executed directly when triggering **Run Build Task** (`kb(workbench.action.tasks.build)`). To do so, select **Configure Default Build Task** from the global **Terminal** menu. This shows you a picker with the available build tasks. Select TypeScript **tsc: build** which generates the following `tasks.json` file in a `.vscode` folder: + +```ts +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "type": "typescript", + "tsconfig": "tsconfig.json", + "problemMatcher": [ + "$tsc" + ], + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} +``` + +Notice that the task has a `group` JSON object which sets the task `kind` to `build` and makes it the default. Now when you select the **Run Build Task** command or press (`kb(workbench.action.tasks.build)`), you are not prompted to select a task and your compile starts. + +> **Tip:** You can also run the program using VS Code's Run/Debug feature. Details about running and debugging Node.js applications in VS Code can be found [here](/docs/nodejs/nodejs-tutorial.md#debugging-your-node-application) + +### Step 4: Reviewing build issues + +The VS Code task system can also detect build issues through a [problem matcher](/docs/editor/tasks.md#defining-a-problem-matcher). A problem matcher parse build output based on the specific build tool and provides integrated issue display and navigation. VS Code ships with many problem matchers and `$tsc` seen above in `tasks.json` is the problem matcher for TypeScript compiler output. + +As an example, if there was a simple error (extra 'g' in `console.log`) in our TypeScript file, we may get the following output from `tsc`: + + HelloWorld.ts(3,17): error TS2339: Property 'logg' does not exist on type 'Console'. + +This would show up in the terminal panel (`kb(workbench.action.terminal.toggleTerminal)`) and selecting the terminal **Tasks - build tsconfig.json** in the terminal view drop-down. + +You can see the error and warning counts in the Status Bar. Click on the error and warnings icon to get a list of the problems and navigate to them. + +![Error in Status Bar](images/compiling/error-status-bar.png) + +You can also use the keyboard to open the list `kb(workbench.actions.view.problems)`. + +>**Tip:** Tasks offer rich support for many actions. Check the [Tasks](/docs/editor/tasks.md) topic for more information on how to configure them. + +## JavaScript source map support + +TypeScript debugging supports JavaScript source maps. To generate source maps for your TypeScript files, compile with the `--sourcemap` option or set the `sourceMap` property in the `tsconfig.json` file to `true`. + +In-lined source maps (a source map where the content is stored as a data URL instead of a separate file) are also supported, although in-lined source is not yet supported. + +## Output location for generated files + +Having the generated JavaScript file in the same folder at the TypeScript source will quickly get cluttered on larger projects. You can specify the output directory for the compiler with the `outDir` attribute. + +```json +{ + "compilerOptions": { + "target": "es5", + "module": "commonjs", + "outDir": "out" + } +} +``` + +## Hiding derived JavaScript files + +When you are working with TypeScript, you often don’t want to see generated JavaScript files in the File Explorer or in Search results. VS Code offers filtering capabilities with a `files.exclude` [workspace setting](/docs/getstarted/settings.md) (**File** > **Preferences** > **Settings**) and you can easily create an expression to hide those derived files: + +`**/*.js: { "when": "$(basename).ts" }` + +This pattern will match on any JavaScript file (`**/*.js`) but only if a sibling TypeScript file with the same name is present. The File Explorer will no longer show derived resources for JavaScript if they are compiled to the same location. + +![Hiding derived resources](images/compiling/hidingDerivedBefore.png) ![Hiding derived resources](images/compiling/hidingDerivedAfter.png) + +To exclude JavaScript files generated from both `.ts` and `.tsx` source files, use this expression: + +```json +"**/*.js": { "when": "$(basename).ts" }, +"**/**.js": { "when": "$(basename).tsx" } +``` + +This is a bit of a trick. The search glob pattern is used as a key. The settings above use two different glob patterns to provide two unique keys but the search will still match the same files. + +## Using newer TypeScript versions + +VS Code ships with a recent stable version of the TypeScript language service and the active version and install location of the TypeScript language service is displayed in the Status Bar when viewing a TypeScript or JavaScript file: + +![TypeScript status bar version](images/compiling/status-bar-version.png) + +>**Tip:** To get a specific TypeScript version, specify `@version` during npm install. For example, for TypeScript 3.2.0, you would use `npm install --save-dev typescript@3.2.0`. To preview the next version of TypeScript, run `npm install --save-dev typescript@next`. + +To use a different TypeScript version by default, configure `typescript.tsdk` in your user [settings](/docs/getstarted/settings.md) to point to a directory containing the TypeScript `tsserver.js` file. You can find the TypeScript installation location using `npm list -g typescript`. The `tsserver.js` file is usually in the `lib` folder. + +For example: + +```json +{ + "typescript.tsdk": "/usr/local/lib/node_modules/typescript/lib" +} +``` + +You can also configure a specific version of TypeScript in a particular workspace by adding a `typescript.tsdk` workspace setting pointing to the directory of the `tsserver.js` file: + +```json +{ + "typescript.tsdk": "./node_modules/typescript/lib" +} +``` + +Note that while `typescript.tsdk` points to the `lib` directory inside of `typescript` in these examples, the `typescript` directory must be a full TypeScript install that contains the TypeScript `package.json` file. + +### Using the workspace version of TypeScript + +If your workspace has a specific TypeScript version, you can switch between the workspace version of TypeScript and the version that VS Code uses by default by opening a TypeScript or JavaScript file in the workspace and clicking on the TypeScript version number in the Status Bar. A message box will appear asking you which version of TypeScript VS Code should use: + +![TypeScript version selector](images/compiling/select-ts-version-message.png) + +You can switch back to the version of TypeScript that comes with VS Code by clicking on the TypeScript version in the Status Bar again. + +## Mixed TypeScript and JavaScript projects + +It is possible to have mixed TypeScript and JavaScript projects. To enable JavaScript inside a TypeScript project, you can set the `allowJs` property to `true` in the `tsconfig.json`. + +>**Tip:** The `tsc` compiler does not detect the presence of a `jsconfig.json` file automatically. Use the `–p` argument to make `tsc` use your `jsconfig.json` file, e.g. `tsc -p jsconfig.json`. + +## Next steps + +Read on to find out about: + +* [Debugging TypeScript](/docs/typescript/typescript-debugging.md) - Configure the debugger for your TypeScript project. + + +## Common questions + +### How do I resolve a TypeScript "Cannot compile external module" error? + +If you get that error, resolve it by creating a `tsconfig.json` file in the root folder of your project. The tsconfig.json file lets you control how Visual Studio Code compiles your TypeScript code. For more information, see the [tsconfig.json overview](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html). + +### Why do I get different errors and warnings with VS Code than when I compile my TypeScript project? + +VS Code ships with a recent stable version of the TypeScript language service and it may not match the version of TypeScript installed globally on your computer or locally in your workspace. For that reason, you may see differences between your compiler output and errors detected by the active TypeScript language service. See [Using newer TypeScript versions](/docs/languages/typescript.md#using-newer-typescript-versions) for details on installing a matching TypeScript version. + +### Can I use the version of TypeScript that ships with VS 2015? + +No, the TypeScript language service which ships with Visual Studio 2015 and 2017 isn't compatible with VS Code. You will need to install a separate version of TypeScript from [npm](https://www.npmjs.com/package/typescript). + +### Why are some errors reported as warnings? + +By default, VS Code TypeScript displays code style issues as warnings instead of errors. This applies to: + +* Variable is declared but never used +* Property is declared but its value is never read +* Unreachable code detected +* Unused label +* Fall through case in switch +* Not all code paths return a value + +Treating these as warnings is consistent with other tools, such as TSLint. These will still be displayed as errors when you run `tsc` from the command line. + +You can disable this behavior by setting `"typescript.reportStyleChecksAsWarnings": false` in your User [settings](/docs/getstarted/settings.md). diff --git a/docs/typescript/typescript-debugging.md b/docs/typescript/typescript-debugging.md new file mode 100644 index 0000000000000000000000000000000000000000..d41436f3ba50f128284f0919eba0f4f4b3516303 --- /dev/null +++ b/docs/typescript/typescript-debugging.md @@ -0,0 +1,146 @@ +--- +Order: 4 +Area: typescript +TOCTitle: Debugging +ContentId: 19c60eb6-662b-444a-92f6-009642cc1e5b +PageTitle: TypeScript debugging with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: TypeScript debugging with Visual Studio Code. +MetaSocialImage: images/typescript-tutorial/Languages_typescript.png +--- +# Debugging TypeScript + +Visual Studio Code supports TypeScript debugging through its built-in [Node.js debugger](/docs/nodejs/nodejs-debugging.md) and also through [extensions](/docs/editor/extension-gallery.md) like [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) to support client-side TypeScript debugging. + +## JavaScript source map support + +TypeScript debugging supports JavaScript source maps. To generate source maps for your TypeScript files, compile with the `--sourcemap` option or set the `sourceMap` property in the `tsconfig.json` file to `true`. + +In-lined source maps (a source map where the content is stored as a data URL instead of a separate file) are also supported, although in-lined source is not yet supported. + +For a simple example of source maps in action, see the [TypeScript tutorial](/docs/typescript/typescript-tutorial.md), which shows debugging a simple "Hello World" Node.js application using the following `tsconfig.json` and VS Code default Node.js debugging configuration. + +```json +{ + "compilerOptions": { + "target": "es5", + "module": "commonjs", + "outDir": "out", + "sourceMap": true + } +} +``` + +For more advanced debugging scenarios, you can create your own debug configuration `launch.json` file. To see the default configuration, go to the Debug view (`kb(workbench.view.debug)`) and press the gear icon to **Configure or Fix 'launch.json'**. If you have other debugger extensions installed (such as the Debugger for Chrome), you should select **Node.js** from the drop down. + +![configure launch.json](images/debugging/configure-debugging.png) + +This will create a `launch.json` file in a `.vscode` folder with default values detected in your project. + +```json +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Launch Program", + "program": "${workspaceFolder}/helloworld.ts", + "preLaunchTask": "tsc: build - tsconfig.json", + "outFiles": [ + "${workspaceFolder}/out/**/*.js" + ] + } + ] +} +``` + +VS Code has determined the program to launch, `helloworld.ts`, included the build as a `preLaunchTask`, and told the debugger where to find the generated JavaScript files. + +There is full IntelliSense with suggestions and information for `launch.json` to help you learn about other debug configuration options. You can also add new debug configurations to `launch.json` with the **Add Configuration** button in the lower right. + +![launch.json IntelliSense](images/debugging/launch-json-intellisense.png) + +Also see [Node.js Debugging](/docs/nodejs/nodejs-debugging.md) for examples and further explanations. + +## Mapping the output location + +If generated (transpiled) JavaScript files do not live next to their source, you can help the VS Code debugger locate them by setting the `outFiles` attribute in the launch configuration. Whenever you set a breakpoint in the original source, VS Code tries to find the generated source by searching the files specified by glob patterns in `outFiles`. + +## Client-side debugging + +TypeScript is great for writing client-side code as well as Node.js applications and you can debug client-side source code with extensions such as [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome). + +We'll create a tiny web application to show client-side debugging in action. + +Create a new folder `HelloWeb` and add three files: `helloweb.ts`, `helloweb.html`, and `tsconfig.json` with the following content" + +helloweb.ts + +```typescript +let message : string = "Hello Web"; +document.body.innerHTML = message; +``` + +helloweb.html + +```html + + + TypeScript Hello Web + + + + +``` + +tsconfig.json + +```json +{ + "compilerOptions": { + "target": "es5", + "module": "commonjs", + "outDir": "out", + "sourceMap": true + } +} +``` + +Run `tsc` to build the app and then test by opening `helloweb.html` in your browser (you can right click `helloweb.html` in the File Explorer and select **Copy Path** to paste into your browser). + +To debug the client-side code, install the [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) [extension](/docs/editor/extension-gallery.md). Open the Extensions view (`kb(workbench.view.extensions)`) and search for "Chrome". Install the extension and reload VS Code. + +![debugger for chrome extension](images/debugging/debugger-for-chrome.png) + +In the Debug view, press the gear icon to create a `launch.json` file selecting **Chrome** as the debugger. + +Update the `launch.json` to specify the local file URL to `helloweb.html`: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "chrome", + "request": "launch", + "name": "Launch Chrome against localhost", + "url": "file:///C:/Users/gregvanl/deleteMe/HelloWeb/helloweb.html", + "webRoot": "${workspaceFolder}" + } + ] +} +``` + +The Debug view configuration dropdown will now show the new configuration **Launch Chrome against localhost**. If you run that configuration, your browser will launch with your web page. Open `helloweb.ts` in the editor and click the left gutter to add a breakpoint (it will be displayed as a red circle). Press `kb(workbench.action.debug.start)` to start the debug session, which launches the browser and hits your breakpoint in `helloweb.ts`. + +![client-side debug breakpoint](images/debugging/client-side-debug-breakpoint.png) + +## Common questions + +### Cannot launch program because corresponding JavaScript cannot be found + +You've likely not set `"sourceMap": true` in your `tsconfig.json` or `outFiles` in your `launch.json` and the VS Code Node.js debugger can't map your TypeScript source code to the running JavaScript. Turn on source maps and rebuild your project. diff --git a/docs/typescript/typescript-tutorial.md b/docs/typescript/typescript-tutorial.md new file mode 100644 index 0000000000000000000000000000000000000000..c28dd8ba3540be84fdb831e2c94b6862e2de8dc8 --- /dev/null +++ b/docs/typescript/typescript-tutorial.md @@ -0,0 +1,173 @@ +--- +Order: 1 +Area: typescript +TOCTitle: Tutorial +ContentId: cb4f3742-733c-49d8-96db-d4bf8403bf64 +PageTitle: TypeScript tutorial with Visual Studio Code +DateApproved: 3/7/2019 +MetaDescription: TypeScript tutorial with Visual Studio Code. +MetaSocialImage: images/typescript-tutorial/Languages_typescript.png +--- +# TypeScript tutorial in Visual Studio Code + +[TypeScript](https://www.typescriptlang.org) is a typed superset of JavaScript that compiles to plain JavaScript. It offers classes, modules, and interfaces to help you build robust components. The TypeScript language specification can be found [here](https://github.com/Microsoft/TypeScript/tree/master/doc). + +## Install the TypeScript compiler + +Visual Studio Code includes TypeScript language support but does not include the TypeScript compiler, `tsc`. You will need to install the TypeScript compiler either globally or in your workspace to transpile TypeScript source code to JavaScript (`tsc HelloWorld.ts`). + +The easiest way to install TypeScript is through npm, the [Node.js Package Manager](https://www.npmjs.com/). If you have npm installed, you can install TypeScript globally (`-g`) on your computer by: + +```bash +npm install -g typescript +``` + +You can test your install by checking the version. + +```bash +tsc --version +``` + +## Hello World + +Let's start with a simple Hello World Node.js example. Create a new folder `HelloWorld` and launch VS Code. + +``` +mkdir HelloWorld +cd HelloWorld +code . +``` + +From the File Explorer, create a new file called `helloworld.ts`. + +![create new file](images/tutorial/create-new-file.png) + +Now add the following TypeScript code. You'll notice the TypeScript keyword `let` and the `string` type declaration. + +```typescript +let message : string = "Hello World"; +console.log(message); +``` + +To compile your TypeScript code, you can open the [Integrated Terminal](/docs/editor/integrated-terminal.md) (`kb(workbench.action.terminal.toggleTerminal)`) and typing `tsc helloworld.ts`. This will compile and create a new `HelloWorld.js` JavaScript file. + +![compiled hello world](images/tutorial/compiled-hello-world.png) + +If you have Node.js installed, you can run `node helloworld.js`. + +![run hello world](images/tutorial/run-hello-world.png) + +If you open `helloworld.js`, you'll see that it doesn't look very different from `helloworld.ts`. The type information has been removed and `let` is now `var`. + +```javascript +var message = "Hello World"; +console.log(message); +``` + +## IntelliSense + +In the VS Code, you can see that you get language features such as syntax highlighting and bracket matching. When you were typing in the editor, you may have noticed IntelliSense, the smart code completions and suggestion provided by VS Code and the TypeScript language server. Below you can see the methods of `console` + +![IntelliSense](images/tutorial/intellisense.png) + +When you select a method, you then get parameter help and can always get hover information. + +![parameter help](images/tutorial/parameter-help.png) + +## tsconfig.json + +So far in this tutorial, you have been relying on the TypeScript compiler's default behavior to compile your TypeScript source code. You can modify the TypeScript compiler options by adding a `tsconfig.json` file which defines the TypeScript [project settings](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) such as the [compiler options](https://www.typescriptlang.org/docs/handbook/compiler-options.html) and the files that should be included. + +Add a simple `tsconfig.json` which set the options to compile to ES5 and use **CommonJS** [modules](http://www.commonjs.org/specs/modules/1.0). + +```json +{ + "compilerOptions": { + "target": "es5", + "module": "commonjs" + } +} +``` + +When editing `tsconfig.json`, IntelliSense (`kb(editor.action.triggerSuggest)`) will help you along the way. + +![tsconfig.json IntelliSense](images/tutorial/tsconfig-intellisense.png) + +By default, TypeScript includes all the `.ts` files in the current folder and subfolders if the `files` attribute isn't included so we don't need to list `helloworld.ts` explicitly. + +Now to build from the terminal, you can just type `tsc` and the TypeScript compiler knows to look at your `tsconfig.json` for project settings and compiler options. + +### Change the build output + +Having the generated JavaScript file in the same folder at the TypeScript source will quickly get cluttered on larger projects, so you can specify the output directory for the compiler with the `outDir` attribute. + +```json +{ + "compilerOptions": { + "target": "es5", + "module": "commonjs", + "outDir": "out" + } +} +``` + +Delete `helloworld.js`, run `tsc` again and `helloworld.js` will be placed in an `out` directory. + +See [Compiling TypeScript](/docs/typescript/typescript-compiling.md) to learn about other features of the TypeScript language service and how to use tasks to run your builds directly from VS Code. + +## Error checking + +TypeScript helps you avoid common programming mistakes through strong type checking. For example, if you assign a number to `message`, the TypeScript compiler will complain with **'error TS2322: Type '2' is not assignable to type 'string'**. You can see type checking errors in VS Code both the editor (red squillies with hover information) and the Problems panel (`kb(workbench.actions.view.problems)`). The `[ts]` prefix lets you know this error is coming from the TypeScript language service. + +![incorrect type error](images/tutorial/incorrect-type-error.png) + +## Quick Fixes + +The TypeScript language service has a powerful set of diagnostics to find common coding issues. For example it can analyze your source code and detect unreachable code which are displayed as dimmed in the editor. If you hover over the line of source code, you'll see a hover explaining and if you place your cursor on the line, you'll get a Quick Fix lightbulb. + +![unreachable code detected](images/tutorial/unreachable-code-detected.png) + +Clicking on the lightbulb or pressing `kb(editor.action.quickFix)` brings up the Quick Fix menu where you can select the **Remove unreachable code** fix. + +## Debugging + +VS Code has built-in support for TypeScript debugging. To support debugging TypeScript in combination with the executing JavaScript code, VS Code relies on [source maps](https://developer.mozilla.org/docs/Tools/Debugger/How_to/Use_a_source_map) for the debugger to map between the original TypeScript source code and the running JavaScript. You can create source maps during the build by setting `"sourceMap": true` in your `tsconfig.json`. + +```json +{ + "compilerOptions": { + "target": "es5", + "module": "commonjs", + "outDir": "out", + "sourceMap": true + } +} +``` + +Rebuild by running `tsc` and you should now have a `helloworld.js.map` in the `out` directory next to `helloworld.js`. + +With `helloworld.ts` open in the editor, press `kb(workbench.action.debug.start)`. If you have other debugger extensions installed (such as the Chrome Debug extension), you need to select **Node.js** from the dropdown. + +The debugger will start a session, run your code, and display the "Hello World" message in the Debug console panel. + +![debug console output](images/tutorial/debug-console.png) + +In `helloworld.ts`, set a breakpoint by clicking on the left gutter of the editor. You will see a red circle if the breakpoint is set. Press `kb(workbench.action.debug.start)` again. Execution will stop when the breakpoint is hit and you'll be able to see debugging information such as variable values and the call stack in the Debug view (`kb(workbench.view.debug)`). + +![debug breakpoint](images/tutorial/debug-breakpoint.png) + +See [Debugging TypeScript](/docs/typescript/typescript-debugging.md) to learn more about VS Code's built-in debugging support for TypeScript and how you can configure the debugger for your project scenarios. + +## Next steps + +This tutorial was a quick introduction to using VS Code for TypeScript development. Read on to learn more about using VS Code's compiling and debugging support for TypeScript: + +* [Compiling TypeScript](/docs/typescript/typescript-compiling.md) - Use VS Code's powerful task system for compiling TypeScript. +* [Debugging TypeScript](/docs/typescript/typescript-debugging.md) - Configure the debugger for your TypeScript project. + + +## Common questions + +### Cannot launch program because corresponding JavaScript cannot be found + +You've likely not set `"sourceMap": true` in your `tsconfig.json` and the VS Code Node.js debugger can't map your TypeScript source code to the running JavaScript. Turn on source maps and rebuild your project. diff --git a/github/workflows/code-quality.yml. b/github/workflows/code-quality.yml. new file mode 100644 index 0000000000000000000000000000000000000000..1a2061e425d148f443ad0bcea05ac663cd5bad64 --- /dev/null +++ b/github/workflows/code-quality.yml. @@ -0,0 +1,26 @@ +name: Code Quality Check + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + analysis: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: '8.3' + extensions: mbstring, xml, ctype, iconv, json + + - name: Check for Syntax Errors + run: | + # فحص ملفات الماركدوان للتأكد من عدم وجود أخطاء هيكلية في نماذج الكود + find . -name "*.md" -exec grep -l ' { + if (!$.which('git')) { + $.echo('This command requires git') + $.exit(1) + done() + } + + // Go to _build + if (!$.test('-e', '_build')) { + $.mkdir('_build') + } + $.cd('_build') + + // Clone prod branch of vscode-website + // If it exists, upgrade to latest + if (!$.test('-e', 'vscode-website')) { + $.exec(`git clone --depth=1 --branch=prod ${URL}`) + } else { + $.cd('vscode-website') + $.exec('git pull origin prod') + $.cd('..') + } + + // Copy over MD/asset files + $.mkdir('vscode-website/vscode-docs') + $.cp('-R', ['../blogs', '../docs', '../images', '../release-notes', '../tutorials', '../build', '../api'], 'vscode-website/vscode-docs') + + // Clone tas-client + $.exec(`git clone ${TAS_URL} vscode-website/tas-client`) + $.cd('vscode-website/tas-client') + $.exec('git checkout tags/v1.8-beta') + $.cd('../..') + + // Go to vscode-website + $.cd('vscode-website') + // Run setup to fetch vscode-website-dist + $.echo('BRANCH is ' + BRANCH) + const setup = $.exec(`scripts/setup.sh ${GITHUB_TOKEN} ${BRANCH}`) + if (setup.code !== 0) { + console.log('Failed to setup') + done(setup.stderr) + } + // Run build to sync changes to vscode-website-dist + const build = $.exec(`scripts/build.sh ${BRANCH}`) + if (build.code !== 0) { + console.log('Failed to build') + done(build.stderr) + } +}) diff --git a/images/MDPreviewButton.png b/images/MDPreviewButton.png new file mode 100644 index 0000000000000000000000000000000000000000..eb03a36918d4c03dcdc0dd017f5f01466d5494da Binary files /dev/null and b/images/MDPreviewButton.png differ diff --git a/package.json b/package.json new file mode 100644 index 0000000000000000000000000000000000000000..8e8055651dce42891fbe97a379507e6480b66098 --- /dev/null +++ b/package.json @@ -0,0 +1,15 @@ +{ + "name": "vscode-docs", + "version": "0.10.3", + "author": { + "name": "Microsoft Corporation" + }, + "repository": { + "type": "git", + "url": "https://github.com/Microsoft/vscode-docs.git" + }, + "devDependencies": { + "gulp": "^3.9.1", + "shelljs": "^0.7.8" + } +} diff --git a/release-notes/July_2016.md b/release-notes/July_2016.md new file mode 100644 index 0000000000000000000000000000000000000000..7894dddfd8567f28fe7995a0c1b435a49418c911 --- /dev/null +++ b/release-notes/July_2016.md @@ -0,0 +1,206 @@ +--- +Order: +TOCTitle: July 2016 +PageTitle: Visual Studio Code July 2016 1.4 +MetaDescription: See what is new in the Visual Studio Code July 2016 Release (1.4) +MetaSocialImage: July_2016/social.jpg +--- +# July 2016 (version 1.4) + +During July, we slowed down feature work in favor of reducing our bug backlog and removing engineering debt. However, we were still able to add some improvements. + +Here are the highlights: + +* **Workbench**: Editor actions such as **Open Preview** and **Switch to Changes View** are back on the title bar. IME and Copy/Paste support in the Integrated Terminal. +* **Editor**: Better snippet and suggestions control. New **Insert Snippet** command with dedicated UI. +* **Debugging**: **Restart Frame** action to rerun a specific stack frame. 'Variable paging' feature moved into VS Code and available to all debug extensions. +* **Extension Authoring**: New 'move' commands to better support VIM gestures. Custom link behavior with the `DocumentLinkProvider` API. Expanded Debug Protocol. + +Downloads: [Windows](https://az764295.vo.msecnd.net/stable/6276dcb0ae497766056b4c09ea75be1d76a8b679/VSCodeSetup-stable.exe) | +[OS X](https://az764295.vo.msecnd.net/stable/6276dcb0ae497766056b4c09ea75be1d76a8b679/VSCode-darwin-stable.zip) | Linux 64-bit: [.zip](https://az764295.vo.msecnd.net/stable/6276dcb0ae497766056b4c09ea75be1d76a8b679/VSCode-linux-x64-stable.zip) [.deb](https://az764295.vo.msecnd.net/stable/6276dcb0ae497766056b4c09ea75be1d76a8b679/code_1.4.0-1470329130_amd64.deb) [.rpm](https://az764295.vo.msecnd.net/stable/6276dcb0ae497766056b4c09ea75be1d76a8b679/code-1.4.0-1470329130.el7.x86_64.rpm) | Linux 32-bit: [.zip](https://az764295.vo.msecnd.net/stable/6276dcb0ae497766056b4c09ea75be1d76a8b679/VSCode-linux-ia32-stable.zip) [.deb](https://az764295.vo.msecnd.net/stable/6276dcb0ae497766056b4c09ea75be1d76a8b679/code_1.4.0-1470328389_i386.deb) [.rpm](https://az764295.vo.msecnd.net/stable/6276dcb0ae497766056b4c09ea75be1d76a8b679/code-1.4.0-1470328389.el7.i386.rpm) + +## Editor + +### Snippets and Suggestions + +By default, VS Code shows snippets and completion proposals in one widget. This is not always desirable so we added a new configuration setting called `editor.snippetSuggestions`. To remove snippets from the suggestions widget, set the value to `"none"`. If you'd like to see snippets, you can specify the order relative to suggestions; at the top (`"top"`), at the bottom (`"bottom`"), or inline ordered alphabetically (`"inline"`). The default is `"inline"`. + +In addition, we added a new command to insert a snippet, **Insert Snippet**, which displays the available snippets in a drop down. + +![snippet insert](images/July_2016/insertSnippet.gif) + +### Tab Completion + +The editor now supports `kbstyle(Tab)` completions. You can enable it with the `editor.tabCompletion` setting. After typing the prefix of a snippet, press `kbstyle(Tab)` to insert it. + +![tab completions](images/July_2016/tabCompletion.gif) + +Note that quick suggestions and `kbstyle(Tab)` completion might interfere because the suggestions widget also reacts to `kbstyle(Tab)`. + +Either disable quick suggestions: + +```json + "editor.quickSuggestions": false +``` + +or remove snippets from the suggest widget: + +```json + "editor.snippetSuggestions": "none" +``` + +## Workbench + +### Editor Actions + +When we added Tabs (tabbed headings), we put editor actions (**Switch to Changes View**, **Open Preview**) into the context menu to gain some space. User feedback was clear that this made the actions much harder to discover and so we have added them back to the title header. + +![Menu Group Sorting](images/July_2016/editor-actions-title.png) + +### Drag and Drop + +You can now drag and drop Tabs (tabbed headings) across windows. You can now also drop a folder into VS Code to open it. + +### Git commit message template + +If you have a message template configured in your Git settings, then the Git view in VS Code will show that message in the commit message box by default. Thanks to [William Raiford](https://github.com/bill-mybiz) for contributing this feature. + +### Faster Quick Open + +We made the first steps in improving the performance of **Quick Open**, particularly for large workspaces such as [Chromium](https://www.chromium.org). On Mac (`kbstyle(⌘+P)`) and on Linux (`kbstyle(Ctrl+P)`), **Quick Open** on a Chromium workspace now takes less than half the time it took before. On Windows (`kbstyle(Ctrl+P)`), it originally took twice as long as on Mac and now it is just as fast. We are not finished, expect more performance gains in the next iteration. + +### Integrated Terminal + +The integrated terminal had several changes related to polish and compatibility this release: + +- **IME support**: Input Method Editor (IME) support has been implemented, allowing input of CJK and Indic characters. + + ![IME support in Visual Studio Code](images/July_2016/terminal_ime.png) + +- **Copy and paste support on Windows and Linux**: Proper copy and paste support has arrived for Windows and Linux within the terminal. The default keybindings are `kb(workbench.action.terminal.copySelection)` and `kb(workbench.action.terminal.paste)` respectively. Note that these command keybindings are not assigned by default on Mac but you can easily add [your own keybindings](/docs/getstarted/keybindings.md). +- **Context menu**: A right-click context menu has been added with the options **New Terminal**, **Copy** and **Paste**. +- **Accessibility**: It's now possible to escape focus in the terminal by pressing `kb(editor.action.toggleTabFocusMode)` to enable `kbstyle(Tab)` focus mode, just like in the editor. When this mode is enabled, `kbstyle(Tab)` and `kbstyle(Shift+Tab)` will not be passed to the terminal but instead change the element that is being focused. + +## Languages + +### JSON completions + +There has been some small improvements for the JSON completions: + +- In schema based JSON documents, we offer completions for empty arrays, objects and string if we know the type of a property but the schema doesn't describe any defaults. +- Completion support for the `$schema` property and values. + +## Debugging + +### Restart Frame + +VS Code now supports restarting execution at a stack frame. This can be useful in situations where you have found a problem in your source code and you want to rerun a small portion of the code with modified input values. Stopping and then restarting the full debug session can be very time-consuming. The **Restart Frame** action allows you to re-enter the current function after you have changed variables with the **Set Value** action: + +![Restart Frame](images/July_2016/restartFrame.gif) + +Note that **Restart Frame** won't unroll any state changes, so it may not always work as expected. + +**Restart Frame** is only available if the underlying debug extension supports it and currently only VS Code's built-in Node.js debugging does. Make sure to use a Node.js version >= 5.11 since earlier versions do not work in all situations. + +### Variable Paging + +Previously VS Code expected that large data structures like arrays were broken into "chunks" in a debug extension and consequently only a few debug extensions supported this useful feature. With this release, we have moved this functionality into the VS Code debugger front-end so that all debug extensions can easily benefit from this in the future. + +![Variable Paging](images/July_2016/variablePaging.png) + +See section "Debug Protocol Changes" below for details of how a debug extension can make use of this. + +### Double Click Debug Toolbar Centers + +Double clicking on the Debug view toolbar drag icon will center the Debug toolbar. This makes it easy to restore the default state. + +## Extension Authoring + +### New settings to replace deprecated __characterPairSupport and __electricCharacterSupport. + +The deprecated configuration settings can now both be replaced by the `autoClosingPairs` setting in the language-configuration.json file in your extension. See [#9281](https://github.com/Microsoft/vscode/issues/9281) for detailed instructions. + +### Editor Commands + +In order to allow the [VIM extension](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) to make good progress on their [roadmap](https://github.com/VSCodeVim/Vim/blob/master/ROADMAP.md) particularly on up-and-down motion and `kbstyle(Tab)` related commands, we added the following editor APIs: + +- **Move cursor:** Moves the cursor to different logical positions in the editor - See [9143](https://github.com/Microsoft/vscode/issues/9143). + +```javascript +commands.executeCommand('cursorMove', {to: 'up', by: 'wrappedLine', value: '2'}) +``` + +- **Move active editor:** Moves the active editor across groups or across Tabs within a group - See [8234](https://github.com/Microsoft/vscode/issues/8234#issuecomment-234573410). + +```javascript +commands.executeCommand('moveActiveEditor', {to: 'left', by: 'tab', value: '3'}) +``` + +### Sorting of groups + +Last milestone, we added support to contribute menu items to different places in the editor. This milestone we refined sorting of groups. They are now sorted in lexicographical order with the following defaults/rules. + +The context menu of the editor has these default: + +* `navigation` - The `navigation` group comes first in all cases. +* `1_modification` - This group comes next and contains commands that modify your code. +* `9_cutcopypaste` - The last default group with the basic editing commands. + +![Menu Group Sorting](images/July_2016/groupSorting.png) + +You can add menu items to these groups or add new groups of menu items in between, below, or above. In this release, only the editor context menu allows this grouping control but it will soon be available for the editor title menu and the explorer context menu as well. + +### DocumentLinkProvider API + +VS Code has a built in link detector that finds `http`, `https`, and `file` links to make them clickable in the editor. We have added new API that allows extension writers to add custom link detection logic. Implement a `DocumentLinkProvider` and use the [`registerDocumentLinkProvider`](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.d.ts#L3814) function to register it with the editor. + +### Debug Extension Authoring: Additions to the Debug Protocol + +The [debug protocol](https://github.com/Microsoft/vscode-debugadapter-node/blob/master/protocol/src/debugProtocol.ts) has been extended in the following areas (and VS Code already provides the corresponding UI): + +* **Restart Frame**: If a debug adapter returns the capability `supportsRestartFrame`, VS Code shows a **Restart Frame** action in the context menu of the **CALL STACK** view and calls the new `restartFrame` request upon execution of the **Restart Frame** action. The `restartFrame` request must result in a `StoppedEvent` so that the UI can be updated for the new location. +* **Variable Paging**: 'Variables paging' adds support for paging variables and their children. The debugger UI in VS Code 1.4 uses this to present variables with many children with a better scalable (paged) UI and fetches the children in a piecemeal way. A debug adapter can find out whether the client supports variable paging by checking the value of the `supportsVariablePaging` client capability passed as an argument to the `initializeRequest`.
+Through the optional attributes `indexedVariables` and `namedVariables`, the debug adapter can return both the number of indexed properties (e.g. array slots) and named properties of a variable. These two properties can be returned in all places where a `variablesReference` property is returned, that is in the `Variables` and `Scope` data types and in the `evaluateRequest` response.
+Additional optional attributes have been added to the `variablesRequest` to give the VS Code debugger UI better control over what children of a variable to fetch. An attribute `filter` is used to limit the fetched children to either `indexed` or `named` and the attributes `start` and `count` are used to further limit the children to a certain range. +* **Continued Event**: A debug adapter can now optionally send a `ContinueEvent` to the client to indicate that the execution of the debuggee has continued. +* **Source request supports MIME type**: A debug adapter can now set a `mimeType` attribute on the `SourceRequest` response which a client can use to find a suitable editor. +* **Variable Type client capability**: A debug adapter can find out whether the client shows the variable's type attribute in the UI by checking the value of +the `supportsVariableType` client capability passed as an argument to the `initializeRequest`. + +## Notable Changes + +* [4842](https://github.com/Microsoft/vscode/issues/4842): Allow to disable drag and drop in the files explorer +* [7839](https://github.com/Microsoft/vscode/issues/7839): Sometimes SVG icons do not show up on Windows 7 +* [8788](https://github.com/Microsoft/vscode/issues/8788): Weird tabs auto scrolling behaviour +* [8704](https://github.com/Microsoft/vscode/issues/8704): Deleting folder containing dirty files closes dirty editors +* [8617](https://github.com/Microsoft/vscode/issues/8617): Run selected text in active terminal is not running the selected text on Windows +* [8219](https://github.com/Microsoft/vscode/issues/8219): Lines containing unicode characters in integrated terminal differ in height +* [9010](https://github.com/Microsoft/vscode/issues/9010): Global search and replace: Support regular expression variables in replace + +These are the [closed bugs](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+label%3Abug+milestone%3A%22July+2016%22+is%3Aclosed) and these are the [closed feature requests](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+milestone%3A%22July+2016%22+is%3Aclosed+label%3Afeature-request) for the 1.4 update. + +## Thank You + +Last but certainly not least, a big *__Thank You!__* to the following folks that helped to make VS Code even better: + +* [Lucian Wischik (@ljw1004)](https://github.com/ljw1004): Fix small typo [PR vscode-languageserver-node-example#17](https://github.com/Microsoft/vscode-languageserver-node-example/pull/17) +* [Markus Westerlind (@Marwes)](https://github.com/Marwes): DidOpenTextDocumentParams does not extend TextDocumentIdentifier [PR language-server-protocol#36](https://github.com/Microsoft/language-server-protocol/pull/36) +* [Eshwar Andhavarapu (@gontadu)](https://github.com/gontadu): Added more T-SQL keywords [PR #9469](https://github.com/Microsoft/vscode/pull/9469) +* [Pouya Kary (@pmkary)](https://github.com/pmkary): Added missing "rem" unit [PR #9497](https://github.com/Microsoft/vscode/pull/9497) +* [xzper (@f111fei)](https://github.com/f111fei): + * Fix extracting zip file [PR #7599](https://github.com/Microsoft/vscode/pull/7599) + * Fix installing extension by dropping [PR #8786](https://github.com/Microsoft/vscode/pull/8786) + * Fix debounceEvent [PR #9186](https://github.com/Microsoft/vscode/pull/9186) +* [Sorin Iclanzan (@iclanzan)](https://github.com/iclanzan): Fix sensitivity not always being applied. [PR #9005](https://github.com/Microsoft/vscode/pull/9005) +* [Tamas Kiss (@kisstkondoros)](https://github.com/kisstkondoros): + * Fixes invisible cursor in long editor lines [PR #8854](https://github.com/Microsoft/vscode/pull/8854) + * Fixes mousewheel zoom in case of inline diff view [PR #8853](https://github.com/Microsoft/vscode/pull/8853) + * New cursor animation styles implemented [PR #8153](https://github.com/Microsoft/vscode/pull/8153) +* [一丝 (@yisibl)](https://github.com/yisibl): Add Selection To Previous Find Match [PR #8677](https://github.com/Microsoft/vscode/pull/8677) +* [Giorgos Retsinas (@elemongw)](https://github.com/elemongw): [Mac] `kbstyle(Ctrl+P)` and `kbstyle(Ctrl+N)` for up and down navigation. [PR #7316](https://github.com/Microsoft/vscode/pull/7316) +* [William Raiford (@bill-mybiz)](https://github.com/bill-mybiz): Git commit message templates, restore previous message on undo. [PR #8933](https://github.com/Microsoft/vscode/pull/8933) +* [Georgios Kalpakas (@gkalpak)](https://github.com/gkalpak): docs(LanguageConfiguration): fix typo [PR #8703](https://github.com/Microsoft/vscode/pull/8703) +* [David Wilson (@daviwil)](https://github.com/daviwil): + * Roll back PowerShell syntax definition [PR #9922](https://github.com/Microsoft/vscode/pull/9923) + * Fixes for PowershellSyntax.tmLanguage [PR #9707](https://github.com/Microsoft/vscode/pull/9707) +* [David Hollinger III (@dhollinger)](https://github.com/dhollinger): Remove .pp from Ruby extension list [PR #8637](https://github.com/Microsoft/vscode/pull/8637) \ No newline at end of file diff --git a/release-notes/June_2016.md b/release-notes/June_2016.md new file mode 100644 index 0000000000000000000000000000000000000000..44e295626ea070a6f0e30b4b3ada0feb93173b13 --- /dev/null +++ b/release-notes/June_2016.md @@ -0,0 +1,516 @@ +--- +Order: +TOCTitle: June 2016 +PageTitle: Visual Studio Code June 2016 1.3 +MetaDescription: See what is new in the Visual Studio Code June 2016 Release (1.3) +MetaSocialImage: June_2016/social.jpg +--- +# June 2016 (version 1.3) + +## 1.3.1 Recovery build + +To fix several issues, we're releasing a 1.3.1 recovery build. You can view the resolved issues [here](https://github.com/Microsoft/vscode/milestone/24?closed=1). + +Downloads: [Windows](https://az764295.vo.msecnd.net/stable/e6b4afa53e9c0f54edef1673de9001e9f0f547ae/VSCodeSetup-stable.exe) | +[OS X](https://az764295.vo.msecnd.net/stable/e6b4afa53e9c0f54edef1673de9001e9f0f547ae/VSCode-darwin-stable.zip) | Linux 64-bit [.zip](https://az764295.vo.msecnd.net/stable/e6b4afa53e9c0f54edef1673de9001e9f0f547ae/VSCode-linux-x64-stable.zip) [.deb](https://az764295.vo.msecnd.net/stable/e6b4afa53e9c0f54edef1673de9001e9f0f547ae/code_1.3.1-1468329898_amd64.deb) [.rpm](https://az764295.vo.msecnd.net/stable/e6b4afa53e9c0f54edef1673de9001e9f0f547ae/code-1.3.1-1468329898.el7.x86_64.rpm) | Linux 32-bit [.zip](https://az764295.vo.msecnd.net/stable/e6b4afa53e9c0f54edef1673de9001e9f0f547ae/VSCode-linux-ia32-stable.zip) [.deb](https://az764295.vo.msecnd.net/stable/e6b4afa53e9c0f54edef1673de9001e9f0f547ae/code_1.3.1-1468330706_i386.deb) [.rpm](https://az764295.vo.msecnd.net/stable/e6b4afa53e9c0f54edef1673de9001e9f0f547ae/code-1.3.1-1468330706.el7.i386.rpm) + +## June Release Summary + +We're really excited about the June release of VS Code. We've made some big changes to Extension management (dedicated Extensions View) and added Tabs (tabbed editor panes). Other new features include global Search and Replace, improved Drag and Drop and optional indentation guides. All of this along with enhancements to existing features like the Integrated Terminal and delivering a set of important bug fixes. + +Here are the highlights: + +* **Tabs**: Tabbed editor panes allow you to quickly navigate to your files and organize your workbench. +* **Extensions**: New in-product Extensions View to quickly find, install and manage your extensions. +* **Workbench**: Enhanced Drag and Drop, Preview Editors to conserve your editor panes, and multiple Integrated Terminals. +* **Editor**: Global Search and Replace, Indent Guides, Problems panel to view errors and warnings. +* **Languages**: Better, more complete Emmet support, Atom JavaScript grammar extension. +* **Debugging**: Lots of improvements including support for attaching to running Node.js processes and changing variable values during a debug session. +* **Extension Authoring**: A new contribution point for menu bars and context menus. New APIs to open non-text resources and add editor decorator attachments. + +## Tabs + +With this release, VS Code shows open files as Tabs in the title area above the editor. You can move Tabs around via Drag and Drop to organize your files or right-click on a Tab to perform useful file specific actions. + +![Tabs](images/June_2016/tabs.png) + +If you prefer not to use Tabs, you can disable them through the `workbench.editor.showTabs` setting. + +When there is not enough available space to show all files, you will see Tabs overflowing to the left and right. You can always use the mouse to scroll left and right across all tabs. The little overflow icon (see image below) is enabled as soon as there are Tabs outside of the visible view. Clicking on the overflow icon shows a list of all Tabs opened in the group. + +![Tabs Overflow](images/June_2016/overflow.png) + +You can use the new `workbench.editor.openPositioning` setting to control where new editors should open. By default they open to the right of the active Tab, but you can change this to open to the left, or to the beginning or end of all editors. + +### Open Editors View + +The new **OPEN EDITORS** view in the Explorer is the replacement to the previous **WORKING FILES** view. + +![Open editors view](images/June_2016/open_editors.png) + +The **OPEN EDITORS** view is a visual representation of the editor (open file) stacks: + +* Each editor group with the editors that belong to it is shown. +* Clicking on an editor will make it active and open it in the corresponding group. +* Top level actions to close all or save all open editors. +* Editor level actions to close or save an editor. +* Context menu actions provide more refined actions. +* It is possible to drag and drop editors between editor groups or from the Explorer + +You can hide the **OPEN EDITORS** view by setting the number of visible items to 0, with `"explorer.openEditors.visible": 0`. + +**Note:** Since the WORKING FILES view has been deleted, please refer to [this issue](https://github.com/Microsoft/vscode/issues/6605) to get an overview of the new or changed command identifiers. + +### More on Editor Stacks + +As a preparation for enabling Tabs in the workbench, we revisited how you can interact with editors in VS Code. Many users coming from other tools were confused by some of the editor (open file) behavior in VS Code. + +For example: + +* Closing a dirty editor (an editor with an unsaved file) did not prompt for saving. +* Closing an editor, closed the entire group without revealing the previous editor. +* The editor history showed a list of all editors ever opened and not a list of editors you opened in a group. +* **WORKING FILES** view in the Explorer was a confusing concept. + +With editor **stacks**, we've tried to address these issues: + +* You can open up to 3 **editor groups** side by side and each group contains a **stack of editors**. +* Every time you open an editor, it is added to the top of the stack. +* Closing an editor from a group reveals the editor that was previously opened in that group until the last editor closes and the group hides. +* You get prompted to save for dirty editors. + +Use `kb(workbench.action.openPreviousRecentlyUsedEditorInGroup)` to bring up a list of most recently used editors of a group for navigation. Use the **View: Show All Editors** command to show a list of all open editors across all groups. + +![Editor Stacks](images/June_2016/stacks.png) + +Note that the behavior of editor stacks is independent from having Tabs enabled or not. You will benefit from these changes even if you don't want to use Tabs. + +**Note:** Due to the large conceptual impact of editor stacks, many command ids have been renamed and new commands introduced. Please refer to [this issue](https://github.com/Microsoft/vscode/issues/6605) that documents the changes. It also provides guidance if you liked the previous behavior and explains how to change key bindings back to the old behavior. + +## Extension Management + +We have introduced a new Extensions View to improve finding, installing, and updating VS Code [extensions](/docs/editor/extension-gallery.md). + +To display the Extensions View, click the Extensions View icon or press `kb(workbench.view.extensions)`: + +![extension view icon](images/June_2016/extensions-view-icon.png) + +By clicking on the `...` **More Actions** button, it is possible to show: + +* The list of currently installed extensions +* The list of outdated extensions that can be updated +* The list of recommended extensions based on your workspace +* The list of globally popular extensions + +Clearing the search box, shows the list of installed extensions. + +Browsing through a list of extensions, it is possible to install, uninstall or update them. Clicking on an extension will display the detailed description in the editor area. + +![Extensions View](images/June_2016/extensions_viewlet.png) + +## Workbench + +### Errors and Warning in the Problems panel + +With the June release, we now offer a new **Problems** panel, docked at the bottom of VS Code, that shows errors, warnings and other information generated by different sources like language servers, linters and others. In previous releases, we showed the errors and warnings in the quick box at the top of the editor. We have received feedback from users that this made it difficult to review errors and warnings while editing files. The new panel makes it easy to navigate through your errors and warnings and fix them while the editor is still open. + +![Problems](images/June_2016/problems.png) + +A filter box is provided to search and filter among the problems shown. You can either filter by type or by text. For example, 'errors' will filter for all problems of type error. 'character' will filter for problems with messages containing the word 'character'. + +You can open the **Problems** panel by: + +* Using `kb(workbench.actions.view.problems)` +* From the **View** | **Problems** menu +* From the **View** > **Show Problems** command in the **Command Palette** + +The key binding `kb(workbench.actions.view.problems)` that was used to show errors and warnings in the quick open/quick box will now open the **Problems** panel. + +By default, the **Problems** panel scrolls and shows problems for your active file. If you don't want this automatic reveal behavior, you can disable it through a setting `problems.autoReveal`. Set `problems.autoReveal` to `false` to prevent your Problems view from changing as you switch between active files. + +>**Note:** This view is just a representation of markers generated by the language servers or linters or build tasks or any external builders configured in or outside your workspace. You have to configure or customize them appropriately in order to see the expected problems. + +### More powerful Drag and Drop + +With all the work on Tabs, we also looked at improving the Drag & Drop support in the editor. We always allowed you to drop files from outside VS Code into the editor to open the files and now there is a lot more that you can do: + +#### Drop to Split + +Drag some files to the left or right area of an editor to open it to the side of that editor. You can either drag from the Explorer or a Tab if Tabs are enabled. + +![Drop to split](images/June_2016/dnd_editor.gif) + +#### Drop Feedback + +Whenever you are dragging files or a Tab over the editor area, you now get drop feedback to indicate the target position of the drop. + +#### Drag from Explorer and Opened Editors view + +You can now drag a file or editor from the Explorer and the **OPEN EDITORS** view to the editor space to open it at a specific location. + +### Preview Editors + +Closely related to editor stacks and Tabs are **preview editors**. If you are browsing many files, you might not want to see a Tab opened for each file you open. Preview editors help reduce the number of opened editors (and Tabs) by reusing the current editor. A file will open in preview mode if you open it by single clicking in the Explorer. As long as the editor stays in preview mode, other files will open in the same location as the preview editor. + +Certain actions cause a preview editor to become a normal editor: + +* When you modify the contents of a file, the editor will be kept open. +* The same is true for when you double-click on a file in the Explorer or inside a Tab or move a file to a specific editor group. + +Preview editors are indicated using an italic font style. + +![Preview Editor](images/June_2016/preview_editor.png) + +We introduced new settings to control the behavior of preview editors: + +* `workbench.editor.enablePreview` to globally enable or disable preview editors. +* `workbench.editor.enablePreviewFromQuickOpen` to enable or disable preview editors when opened from quick box/quick open. + +### Integrated Terminal + +The integrated terminal that was introduced in VS Code 1.2.0 has seen many improvements this release, the primary one being the ability to launch and use multiple terminals at the same time. Terminal instances can be added by hitting the plus icon on the top-right of the **TERMINAL** panel or by triggering the `kb(workbench.action.terminal.new)` command. This creates another entry in the dropdown list that can be used to switch between them. + +![Multiple terminal instances](images/June_2016/terminal_multiple_instances.png) + +Several new commands were added to aid with management of the **TERMINAL** panel and its terminal instances. + +They are: + +* `workbench.action.terminal.focus`: Focus the terminal. This is like toggle but focuses the terminal instead of hides it, if it is visible. +* `workbench.action.terminal.focusNext`: Focuses the next terminal instance. +* `workbench.action.terminal.focusPrevious`: Focuses the previous terminal instance. +* `workbench.action.terminal.kill`: Remove the current terminal instance. + +The ability to run selected text in the current terminal has been added through the `workbench.action.terminal.runSelectedText` command. + +To use this command, select text in an editor and run the command via the **Command Palette**: + +![Run selected text](images/June_2016/terminal_run_selected.png) + +![Run selected text result](images/June_2016/terminal_run_selected_result.png) + +The following improvements were also added: + +* Copy and paste on Linux and Windows is now available using `kbstyle(Ctrl+Insert)` and `kbstyle(Shift+Insert)` respectively. This is temporarily non-configurable until we can [route custom copy/paste keybindings](https://github.com/sourcelair/xterm.js/issues/118) to the xterm.js library. +* CJK characters should now use the correct width. Credit for this goes to [@jerch](https://github.com/jerch) in [this PR](https://github.com/sourcelair/xterm.js/pull/144). +* Performance of the terminal has improved significantly and should no longer perform poorly when running commands that produce large output. +* `kbstyle(Ctrl+Left)` and `kbstyle(Ctrl+Right)` now tells the underlying shell to jump over words in the input. +* Terminal cursor blinking is now enabled by default. It shares the configuration value with the editor's `editor.cursorBlinking` setting. +* A hollow cursor is shown when the terminal is not focused. +* Terminal font size and line height can be customized via settings, thanks to a [PR](https://github.com/Microsoft/vscode/pull/6998) from [@kisstkondoros](https://github.com/kisstkondoros). +* Selection has been improved to now select the full line, contain no margin and also invert the text colors. + ![Terminal selection has been improved](images/June_2016/terminal_selection.png) +* Arguments can be passed to the terminal shell on Linux and OS X using the `terminal.integrated.shellArgs.*` settings. + +### Command Palette: File: Open Recent in new Window + +The command **File: Open Recent** from the **Command Palette** makes it very easy to quickly switch between previously opened folders or files. Usually the selected file or folder would open in the running instance. In this release, we added support to open into a new window if you select an entry while having the `kbstyle(Ctrl)` (`kbstyle('Cmd')` on Mac) key pressed. + +### Restore Full screen + +A new setting `window.restoreFullscreen` has been added to open VS Code in full screen if it was previously closed in full screen mode. + +## Editor + +### Global Search and Replace + +[Global Search and Replace](https://github.com/Microsoft/vscode/issues/1690) was one of the most requested features from our users. With this release, we enhanced our Search view to include Replace functionality so that you can replace text across multiple files. You can replace in all files or pick file by file or result by result. You can also exclude results or files and then perform replace on the rest. The Search view gives you a nice preview and clicking on a pending change will bring up the Diff editor view showing the file before and after replace. + +![Search and Replace](images/June_2016/searchAndReplace.png) + +Replace functionality can be accessed: + +* In the **Search View** by expanding the Search textbox +* Using `kb(workbench.action.replaceInFiles)`, from the **Edit** | **Replace in Files** menu +* Using **Replace in Files** command in the **Command Palette** + +>**Note:** Since Search has a limitation of showing a maximum of 2048 results, Replace currently has the same limitation. + +### Indent Guides + +VS Code can now show indent guides, enabled with the `editor.renderIndentGuides` setting. + +![Editor Indent Guides](images/June_2016/editor-indent-guides.jpg) + +### Suggestions for command identifiers + +When authoring the `keybindings.json` file, you now get completions for the available commands. + +![Command Completions](images/June_2016/commad_ids.png) + +### Editor Font Zooming with mouse wheel + +Thanks to [@kisstkondoros](https://github.com/kisstkondoros), with [PR #6990](https://github.com/Microsoft/vscode/pull/6990), after setting `editor.mouseWheelZoom: true`, it is possible to change the font size of the editors by pressing `kbstyle(Ctrl)` (`kbstyle('Cmd')` on Mac) and scrolling with the mouse wheel: + +![Mouse Wheel Zoom](images/June_2016/editor-mouse-wheel-zoom.gif) + +### Multiline Find + +We have added support for multiline Find and Replace: + +![Editor Indent Guides](images/June_2016/multiline-find.gif) + +### Emmet + +Thanks to some great support from Denis Malinochkin ([@mrmlnc](https://github.com/mrmlnc)) through Pull Requests and testing help, we are now covering many more Emmet features (Wrap with Abbreviation, Remove Tag, Update Tag, Balance, Toggle Comment, ...). + +## Languages + +### Extract CSS/LESS/SCSS and JSON into extensions + +The CSS, LESS, and SCSS language support has been refactored to be regular VS Code extensions. As all these languages are based on the same code base, they share the same language server. The language server runs in a separate node process, using the [language server protocol](https://microsoft.github.io/language-server-protocol) to communicate with VS Code. + +### Extract Markdown into an extension + +The Markdown language support has been refactored to be a regular VS Code extension. It uses the Markdown TextMate grammar for syntax highlighting source and renders the Markdown as HTML using the [markdown-it library](https://github.com/markdown-it/markdown-it) which implements the [CommonMark Spec](http://spec.commonmark.org/0.25/). + +### Atom JavaScript grammar + +As an alternative to the built-in JavaScript grammar, you can now install the [Atom JavaScript grammar](https://marketplace.visualstudio.com/items?itemName=ms-vscode.js-atom-grammar). It differs from the built-in grammar in that it creates tokens for variable and function references which, if supported by the theme, can be colorized differently. + +## Debugging + +### Moveable Debug Toolbar + +Initiated by this [user request](https://github.com/Microsoft/vscode/issues/4580), it is now possible to drag the debug toolbar horizontally: + +![Drag debug toolbar](images/June_2016/dnd_debug.gif) + +### Changing Variable Value + +We now support changing the value of simple variables if a debug extension supports this. + +Node Debug is the first extension to do so: + +![Drag debug toolbar](images/June_2016/set_variable_value.gif) + +A simple variable is a leaf in the variables tree, e.g. a variable, an object property, or an array element. + +### Show Variable Type on Hover + +If a debug extension supports variable types, we now show the type when hovering over the variable name. + +### Step Back + +If a debug extension supports _step back_ we now expose a step back action and button: + +![Step back](images/June_2016/step_back.png) + +### OS specific launch configurations + +Initiated by a [user request](https://github.com/Microsoft/vscode/issues/1873), it is now possible to specify OS specific configurations inside a `launch.json`: + +```json +{ + "type": "node", + "request": "launch", + "runtimeExecutable": "mynode", + "windows": { + "runtimeExecutable": "mynode.exe" + } +} +``` + +## Node.js Debugging + +### Attach to Process + +Node.js debugging now supports attaching to a Node.js process that has not been started in debug mode. This can be useful if you need to debug a production server that cannot always run in debug mode for performance reasons. + +In order to attach to a Node.js process, you specify its _process id_ via a `processId` attribute in an `attach` launch configuration. + +Since it is not very practical to always having to edit the launch configuration before starting a debug session, we've introduced a new type of variable that can bind to an interactive UI, e.g. to a process picker: + +![Process Picker](images/June_2016/attach_to_process.png) + +Here is a launch configuration that uses the `${command:PickProcess}` variable to let the user select a Node.js process before starting the debug session: + +```json +{ + "name": "Attach to Process", + "type": "node", + "request": "attach", + "processId": "${command:PickProcess}" +} +``` + +## Extension Authoring + +### Menu Items and Context Menu Entries + +We now allow extension writers to contribute to the Explorer context menu (`explorer/context`), the editor context menus (`editor/context`), and the editor title menu (`editor/title`). + +It works in two steps: + +1. Assign a title and an icon to a command using the enhanced `commands` contribution point. +2. Create menu items using the new `menus` contribution point. + +A menu item is defined for a menu location like `editor/context` and must at least specify the `command` to run. To avoid overly cluttered menus, a menu item should also specify a condition under which it shows. Last, an alternative command and a group into which the item is sorted can be defined. Groups are visually separated and there is a special group called _navigation_ which is the most prominent. + +```json +"commands": [{ + "command": "markdown.showPreview", + "title": "Open Preview", + "icon": { + "light": "./media/Preview.svg", + "dark": "./media/Preview_inverse.svg" + } +}], +"menus": { + "explorer/context": [ + { + "when": "resourceLangId == markdown", + "command": "markdown.showPreview", + "group": "navigation" + } + ] +} +``` + +![Menu contribution](images/June_2016/menus-contributions.png) + +The snippet above adds an entry into the navigation group of the Explorer context menu **when** the resource is of the Markdown language. *Note* that the URI of the current resource is passed to the command when being executed from a menu item. + +### Add decorations before and after text + +New capabilities have been added to the decoration APIs. You can now add 'attachments' before and after a decoration. Attachments can be icons as well as text content that sticks to the decorated text. + +An example are the CSS color decorators attached to color values in the text: + +![Decorator attachment](images/June_2016/color_decorators.png) + +Decoration attachments can be defined on decoration types (see the `before` and `after` properties on `ThemableDecorationInstanceRenderOptions`) and fine-tuned on individual decorations (see the `before` and `after` properties on `ThemableDecorationRenderOptions`). You can review these properties in the `vscode` namespace API [reference](/docs/extensionAPI/vscode-api.md). + +### API tweaks + +* The Uri-class now allows you derive a Uri from an existing one: `someUri.with({scheme: 'newScheme', path: 'newPath'})` +* The `previewHtml` command now allows you to provide a `title`. +* When previewing html, we expose the style of the current theme via class names of the body element. Those are `vscode-light`, `vscode-dark`, and `vscode-high-contrast`. +* Last, there is a new command `vscode.open` to open non-textual resources like images. + +### Debug Extension Authoring: Command Variables + +VS Code has supported variable substitution in `launch.json` configurations for some time. This release introduces a new type of variable that is bound to a VS Code _command_. When a debug session is started, all command variables that occur in the underlying launch configuration are first collected and then executed. Multiple occurrences of a variable do not result in multiple execution. Before the launch configuration is passed to the debug adapter, all variables are substituted with the command results. + +A command is implemented and registered in an extension and its return value is used as the variable's value. The implementation of a command can range from a simple expression with no UI, to some sophisticated functionality based on the UI features available in the extension API. + +An example for this functionality can be found in `node-debug`. Here a variable `${command:PickProcess}` is bound to a process picker command. A new 'Attach to Process' launch configuration uses the variable to let the user pick a Node.js process when running the launch configuration. + +Introducing a new command variable is simple: + +* Implement and register the command in your extension (not in the debug adapter). +* Add a `variables` section to your `debuggers` contribution point. +* Add one name/command-binding per variable. + + For example: + + ``` + "debuggers": { + ... + "variables": { + "RemoteHost": "askUserForRemoteHostCommand" + }, + ... + } + ``` + +* The variable can now be used in any string typed value of a launch configuration as `${command:RemoteHost}`. +* To make the `RemoteHost` variable discoverable for the user consider adding it to the `configurationAttributes` or `initialConfigurations` sections of the `debuggers` contribution point. + +### Debug Extension Authoring: Additions to the Debug Protocol + +The debug protocol has been extended in three areas (and VS Code already provides the corresponding UI): + +* **Editing variables**: If a debug adapter returns the [capability `supportsSetVariable`](https://github.com/Microsoft/vscode-debugadapter-node/blob/master/protocol/src/debugProtocol.ts#L594), VS Code supports setting the value of unstructured (leaf) variables in the Variables view by calling the [`setVariable` request](https://github.com/Microsoft/vscode-debugadapter-node/blob/master/protocol/src/debugProtocol.ts#L476). +* **Stepping backward**: If a debug adapter returns the [capability `supportsStepBack`](https://github.com/Microsoft/vscode-debugadapter-node/blob/master/protocol/src/debugProtocol.ts#L592), VS Code enables the UI for stepping back and will call the [`stepBack` request](https://github.com/Microsoft/vscode-debugadapter-node/blob/master/protocol/src/debugProtocol.ts#L476). +* **Show variable type on hover**: If a debug adapter returns the optional `type` attribute for the [`variable` type](https://github.com/Microsoft/vscode-debugadapter-node/blob/master/protocol/src/debugProtocol.ts#L741), VS Code will show the value of this attribute when hovering over the variable's name. + +### Creating Errors/Warnings from an Extension (Diagnostics) + +With the introduction of the new **Problems** panel, we started to work on support for project wide builders and linters. As a first step, we eliminated the automatic clearing of problems when an document is closed. Otherwise opening and closing a document would change the problem set generated by a project wide builder. Due to this change, extensions like linters generating diagnostics are responsible for clearing them when a document is closed. All extension providers generating diagnostics need to adopt to this change. + +In a linter that uses the `vscode-language-server` node module, this can be achieved as follows: + +```typescript +documents.onDidClose((event) => { + connection.sendDiagnostics({ uri: event.document.uri, diagnostics: [] }); +}); +``` + +## Monaco Editor + +The Monaco Editor is now on [npm](https://www.npmjs.com/package/monaco-editor-core)! It is the VS Code source code editor extracted and packaged as a library that can be integrated in any web application to work in any modern browser. We have created a [playground](https://microsoft.github.io/monaco-editor/index.html) showcasing some of the APIs. You can get it via `npm install monaco-editor`. + +All further Monaco Editor specific release notes will be available at its distribution [repository](https://github.com/Microsoft/monaco-editor/blob/master/CHANGELOG.md). + +![Monaco Editor Playground](images/June_2016/monaco-editor-playground.png) + +### CSS/LESS/SCSS and JSON language services are now available + +Additionally, the CSS/LESS/SASS parser and language intelligence source code has been extracted to a separate node module [vscode-css-languageservice](https://github.com/Microsoft/vscode-css-languageservice) which is used by both the [Monaco editor](https://github.com/Microsoft/monaco-editor) as well as VS Code, bringing the same CSS editing experience to the web browser. + +Same for JSON, where the language service, including the JSON schema validator, were extracted to [vscode-json-languageservice](https://github.com/Microsoft/vscode-json-languageservice) which again is shared with the [Monaco editor](https://github.com/Microsoft/monaco-editor). + +## Notable Bug Fixes + +The SASS mode language id has been renamed from 'sass' to 'scss'. If you have customized any linter settings for Sass, just rename the configuration keys from 'sass.' to 'scss.'. + +* [6316](https://github.com/Microsoft/vscode/issues/6316): Update should reopen all last opened folders +* [1210](https://github.com/Microsoft/vscode/issues/1210): Open file dialog should start in the directory for the current active file +* [7391](https://github.com/Microsoft/vscode/issues/7391): editor becomes unresponsive all the time since last update + * This fix improves the memory footprint of all colorizers through the use of immutable linked lists for representing colorizer states in-between lines in [vscode-textmate](https://github.com/Microsoft/vscode-textmate). +* [8173](https://github.com/Microsoft/vscode/issues/8173): Noticeable delay opening a Markdown file (source) + * The implementation of a 10x faster hand-written plist parser for TextMate grammars improves the start-up time of all colorizers. We are looking into extracting this implementation to its own node module. + +In addition, the following bugs were fixed with the Integrated Terminal: + +* [#7911](https://github.com/Microsoft/vscode/issues/7911): Terminal lines appears to have margin +* [#7684](https://github.com/Microsoft/vscode/issues/7684): Clicking into editor does not properly take focus from Terminal view +* [#7458](https://github.com/Microsoft/vscode/issues/7458): Runaway terminalProcess processes +* [#6738](https://github.com/Microsoft/vscode/issues/6738), [#7442](https://github.com/Microsoft/vscode/issues/7442), [#7444](https://github.com/Microsoft/vscode/issues/7444): Several issues related to resizing the terminal +* [#6743](https://github.com/Microsoft/vscode/issues/6743): Mouse wheel scrolling in integrated terminal only works on filled areas +* [#7357](https://github.com/Microsoft/vscode/issues/7357): Invoking the terminal sometimes yields an error "Cannot set property 'innerHTML' of undefined" +* [#6457](https://github.com/Microsoft/vscode/issues/6457): vim overrides the terminal color scheme + +These are the [closed bugs](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+label%3Abug+milestone%3A%22June+2016%22+is%3Aclosed) and these are the [closed feature requests](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+milestone%3A%22June+2016%22+is%3Aclosed+label%3Afeature-request) for the 1.3 update. + +## Downloads + +Downloads: [Windows](https://az764295.vo.msecnd.net/stable/e724f269ded347b49fcf1657fc576399354e6703/VSCodeSetup-stable.exe) | +[OS X](https://az764295.vo.msecnd.net/stable/e724f269ded347b49fcf1657fc576399354e6703/VSCode-darwin-stable.zip) | Linux 64-bit [.zip](https://az764295.vo.msecnd.net/stable/e724f269ded347b49fcf1657fc576399354e6703/VSCode-linux-x64-stable.zip) [.deb](https://az764295.vo.msecnd.net/stable/e724f269ded347b49fcf1657fc576399354e6703/code_1.3.0-1467909982_amd64.deb) [.rpm](https://az764295.vo.msecnd.net/stable/e724f269ded347b49fcf1657fc576399354e6703/code-1.3.0-1467909982.el7.x86_64.rpm) | Linux 32-bit [.zip](https://az764295.vo.msecnd.net/stable/e724f269ded347b49fcf1657fc576399354e6703/VSCode-linux-ia32-stable.zip) [.deb](https://az764295.vo.msecnd.net/stable/e724f269ded347b49fcf1657fc576399354e6703/code_1.3.0-1467910772_i386.deb) [.rpm](https://az764295.vo.msecnd.net/stable/e724f269ded347b49fcf1657fc576399354e6703/code-1.3.0-1467910772.el7.i386.rpm) + +## Thank You + +Last but certainly not least, a big *__Thank You!__* to the following folks that helped to make VS Code even better: + +* [Denis Malinochkin (@mrmlnc)](https://github.com/mrmlnc): Emmet - support all the features [PR #7926](https://github.com/Microsoft/vscode/pull/7926), [PR #8155](https://github.com/Microsoft/vscode/pull/8155), [PR #8489](https://github.com/Microsoft/vscode/pull/8489) +* [Rob Lourens (roblourens)](https://github.com/roblourens): UI support for TimeTravel Debugging [PR #7734](https://github.com/Microsoft/vscode/pull/7734) +* [xzper (f111fei)](https://github.com/f111fei): Debug: Fix setConfiguration error when name is null or undefined [PR #7636](https://github.com/Microsoft/vscode/pull/7636) +* [Thomas Stringer (tstringer)](https://github.com/tstringer): Added remove and disable all breakpoints actions [PR #7627](https://github.com/Microsoft/vscode/pull/7627) +* [Ed Munoz (edumunoz)](https://github.com/edumunoz): + * Remove leaked breakpoint after stopping with run-to-cursor [PR #7367](https://github.com/Microsoft/vscode/pull/7367) + * report RunToCursorAction as not supported when session not stopped [PR #7371](https://github.com/Microsoft/vscode/pull/7371) +* [Giorgos Retsinas (@elemongw)](https://github.com/elemongw): Open window on activate when all windows are closed [PR #7547](https://github.com/Microsoft/vscode/pull/7547) +* [Andrew Arnott (@AArnott)](https://github.com/AArnott): LS Protocol-Clarifications regarding JSON-RPC header [PR #15](https://github.com/Microsoft/language-server-protocol/pull/15) +* [Vaclav Pavlin (@vpavlin)](https://github.com/vpavlin): LS Protocol-Fix typos in protocol.md [PR #20](https://github.com/Microsoft/language-server-protocol/pull/20) +* [Tamas Kiss (@kisstkondoros)](https://github.com/kisstkondoros): + * Gutter icon background size limited [PR #6553](https://github.com/Microsoft/vscode/pull/6553) + * Horizontal selection movement implemented [PR #6887](https://github.com/Microsoft/vscode/pull/6887) + * Option to hide the status bar implement [PR #6942](https://github.com/Microsoft/vscode/pull/6942) + * Allow zooming with ctrl+mousewheel combination [PR #6990](https://github.com/Microsoft/vscode/pull/6990) + * Add an option to display control characters [PR #7578](https://github.com/Microsoft/vscode/pull/7578) + * fix for "screen cheese with long error messages" [PR #8432](https://github.com/Microsoft/vscode/pull/8432) +* [Basarat Ali Syed (@basarat)](https://github.com/basarat): fix : Standalone Monaco text edit validation [PR #7864](https://github.com/Microsoft/vscode/pull/7864) +* [Christian Svensson (@csvn)](https://github.com/csvn): Added order to snippet tab stops [PR #7925](https://github.com/Microsoft/vscode/pull/7925) +* [Phill (@ph1ll)](https://github.com/ph1ll): fix 'shaddow' typo [PR #7981](https://github.com/Microsoft/vscode/pull/7981) +* [Huachao Mao (@Huachao)](https://github.com/Huachao): Add Productivity into extension categories [PR #7304](https://github.com/Microsoft/vscode/pull/7304) +* [Sajjad Hashemian (@sijad)](https://github.com/sijad): + * Improve 'Open in Terminal' on OS X. [PR #6136](https://github.com/Microsoft/vscode/pull/6136) + * Show warning for a long commit message [PR #7399](https://github.com/Microsoft/vscode/pull/7399) +* [Eshwar Andhavarapu (@gontadu)](https://github.com/gontadu): + * Addition of USE EXEC OPENQUERY syntax [PR #8046](https://github.com/Microsoft/vscode/pull/8046) + * Added .dsql and .psql filetypes [PR #7491](https://github.com/Microsoft/vscode/pull/7491) +* [Cătălin Mariș (@alrra)](https://github.com/alrra): Treat `.webmanifest` files as JSON [PR #8019](https://github.com/Microsoft/vscode/pull/8019) +* [Øyvind Kallstad (@gravejester)](https://github.com/gravejester): Refactored PowerShell language definitions [PR #7522](https://github.com/Microsoft/vscode/pull/7522) +* [Jan Niklas Hasse (@jhasse)](https://github.com/jhasse): Highlight .mk files as a Makefile [PR #7328](https://github.com/Microsoft/vscode/pull/7328) +* [Christian Heilmann (@codepo8)](https://github.com/codepo8): Adding autocomplete values of to input/select/textarea [PR #7152](https://github.com/Microsoft/vscode/pull/7152) diff --git a/release-notes/May_2016.md b/release-notes/May_2016.md new file mode 100644 index 0000000000000000000000000000000000000000..5a80f39342f184e695ca8615f29221a78b23f0eb --- /dev/null +++ b/release-notes/May_2016.md @@ -0,0 +1,285 @@ +--- +Order: +TOCTitle: May 2016 +PageTitle: Visual Studio Code May 2016 1.2 +MetaDescription: See what is new in the Visual Studio Code May 2016 Release (1.2) +--- +# May 2016 (version 1.2) + +## 1.2.1 Recovery build + +To fix several performance and Git integration issues, we're releasing a 1.2.1 recovery build. You can view the resolved issues [here](https://github.com/Microsoft/vscode/issues?q=milestone%3A%22June+13th+Stable+Recovery%22+is%3Aclosed). + +Downloads: [Windows](https://az764295.vo.msecnd.net/stable/fe7f407b95b7f78405846188259504b34ef72761/VSCodeSetup-stable.exe) | +[OS X](https://az764295.vo.msecnd.net/stable/fe7f407b95b7f78405846188259504b34ef72761/VSCode-darwin-stable.zip) | Linux 64-bit [.zip](https://az764295.vo.msecnd.net/stable/fe7f407b95b7f78405846188259504b34ef72761/VSCode-linux-x64-stable.zip) [.deb](https://az764295.vo.msecnd.net/stable/fe7f407b95b7f78405846188259504b34ef72761/vscode-amd64.deb) [.rpm](https://az764295.vo.msecnd.net/stable/fe7f407b95b7f78405846188259504b34ef72761/vscode-x86_64.rpm) | Linux 32-bit [.zip](https://az764295.vo.msecnd.net/stable/fe7f407b95b7f78405846188259504b34ef72761/VSCode-linux-ia32-stable.zip) [.deb](https://az764295.vo.msecnd.net/stable/fe7f407b95b7f78405846188259504b34ef72761/vscode-i386.deb) [.rpm](https://az764295.vo.msecnd.net/stable/fe7f407b95b7f78405846188259504b34ef72761/vscode-i386.rpm) + +## 1.2.0 May release + +The May release of VS Code has some great new features, enhancements to existing features, and a set of important bug fixes. + +Here are the highlights: + +* [**Editor**](#editor): Ability to trim automatically inserted whitespace, a new key binding to select all find matches, and the Peek view is now resizable. +* [**Linting**](#linters): ESLint now supports the ability to fix all problems and TSLint supports quick fixes and file exclusion. +* [**Languages**](#languages): Code completion (IntelliSense), Go To and Peek Definition, and Find All Occurrences support for CSS variables in CSS, SCSS, and LESS files. +* [**Workbench**](#workbench): A new integrated Terminal allows you to stay in VS Code while using your platform's shell, we've added the ability to remove key bindings, and we've made *progress* on Tab support, which you can preview using the [Insiders Release](/insiders). +* [**Debugging**](#debugging): You can now control how the Debug Console is revealed and we've improved stepping performance for Node.js applications with large numbers of local variables. +* [**Extensions**](#extension-authoring): You can now list, install, and uninstall extensions from the command line. For extension authors, we've expanded our debug, TextMate grammar, and command APIs and we've improved the Language Server Protocol. + +Please continue reading for more information on what's new in May. + +## Editor + +### Trim auto whitespace + +The editor automatically inserts whitespace when you add a new line, based on indenting rules and the previous line's content. Over time, this can result in unnecessary whitespace being persisted in the file. Thanks to [PR #5423](https://github.com/Microsoft/vscode/pull/5423), the new `editor.trimAutoWhitespace` setting causes the editor to track the automatic whitespace it inserted and remove it if it no longer is needed, for example by typing somewhere else. Please note, this new setting is on by default. + +![Trim Auto Whitespace](images/May_2016/trimAutoWhitespace.gif) + +### Select all find matches + +You can now immediately select all find results by pressing `kb(editor.action.selectAllMatches)`. This is much quicker than doing a find and replace and leverages VS Code's multi-cursor support. Thanks for [PR #5715](https://github.com/Microsoft/vscode/pull/5715)! + +![Find All Matches](images/May_2016/selectAllFindMatches.gif) + +### Configure Word Based Suggestion + +When a language service isn't able to compute semantic completion (suggestions), VS Code defaults to word based completions. This is why for some languages you see an IntelliSense list with every word in the file. Some folks would prefer to not see this list at all so you can now disable word based completions with the `editor.wordBasedSuggestions` setting. + +### Resizable Peek View + +The Peek view editor that shows for reference search and for previewing declarations can now be resized! + +![Peek](images/May_2016/peek.gif) + +## Workbench + +### Tabs + +> Note: Support for Tabs is **not** in the 1.2.0 (May 2016) Stable release. You can preview the experiences below by using the [Insiders Release](/insiders) of VS Code. + +[Tab support](https://github.com/Microsoft/vscode/issues/224) is the number one [User Voice request](https://visualstudio.uservoice.com/forums/293070-visual-studio-code/suggestions/7752519-implement-tabs). While the full implementation will take multiple iterations to fully deliver, we wanted to share progress made during the May iteration. + +During this milestone, we focused on managing *stacks* of open editors. In the picture below, you can see that the left pane has two editors open, the center pane has four, and the right pane has two more. Files listed in italics are *preview* files, they allow you to single click and browse files without cluttering the list of open editors and eventually tabs. + +![Tabs](images/May_2016/tabsprogress.png) + +When you close an editor the last opened editor in the stack is restored, instead of closing the pane as it does today. In addition, we held a number of UX studies that have resulted in further improvements to the design, including: + +* Redesign of the overflow icon +* Ability to specify if files from **Quick Open** are pinned or previewed +* Added a command to turn a previewed file into a pinned file + +This work has been checked into master and you can preview it using the [Insiders Release](/insiders). + +### Integrated terminal + +[Number two](https://visualstudio.uservoice.com/forums/293070-visual-studio-code/suggestions/7752357-integrated-terminal) on User Voice is the request for an integrated terminal, [issue #143](https://github.com/Microsoft/vscode/issues/143). It can be convenient to have a terminal embedded directly in the tool, initially scoped to the workspace you are working in. You don't have to switch windows or alter the state of an existing terminal for a quick task. + +With the May release, we are rolling out the initial version of an integrated terminal. You can open the terminal using `kb(workbench.action.terminal.toggleTerminal)`, from the **View** | **Integrated Terminal** menu, or from the **View** > **Toggle Integrated Terminal** command in the **Command Palette**. + +The shell that is used defaults to `$SHELL` on Linux and OS X, and `%COMSPEC%` on Windows. These can be overridden manually by setting `terminal.integrated.shell.*` in settings. It should act just like the terminal you're familiar with. + +![Terminal](images/May_2016/integrated-terminal.png) + +Please note, this is an early version of what we want to deliver. Currently VS Code only supports a single terminal and there still are missing features like copying and pasting with the keyboard. Windows 10 users may experience problems getting `cmd.exe` to work. If so, please try enabling the legacy terminal as described in [#143](https://github.com/Microsoft/vscode/issues/143#issuecomment-221054202). The full list of current bugs and feature requests can be found [here](https://github.com/Microsoft/vscode/issues?q=is%3Aopen+is%3Aissue+label%3Aintegrated-terminal). + +>**Note:** The **Toggle Integrated Terminal** key binding `kb(workbench.action.terminal.toggleTerminal)` had previously been bound to the **Cycle Between Open Editors** command. You can [customize](https://code.visualstudio.com/docs/getstarted/keybindings#_customizing-shortcuts) the key bindings and change the behavior back if desired. + +### Removing a specific key binding rule + +It is now possible to write a key binding rule that targets the removal of a specific default key binding. With the `keybindings.json`, it was always possible to redefine all the key bindings of VS Code, but it can be very difficult to make a small tweak, especially around overloaded keys, such as `kbstyle(Tab)` or `kbstyle(Escape)`. From now on, simply add a `-` to the `command` and the rule will be a removal rule. + +Here is an example: + +```json +// In Default Keyboard Shortcuts +... +{ "key": "tab", "command": "tab", "when": ... }, +{ "key": "tab", "command": "jumpToNextSnippetPlaceholder", "when": ... }, +{ "key": "tab", "command": "acceptSelectedSuggestion", "when": ... }, +... + +// To remove the second rule, for example, add in keybindings.json: +{ "key": "tab", "command": "-jumpToNextSnippetPlaceholder" } + +``` + +## Languages + +### CSS Variables + +[Variable support in CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) is a new standards proposal currently in [draft](https://drafts.csswg.org/css-variables/) form. VS Code now supports rich code completion (IntelliSense) for CSS variables as well as Go To Definition, Peek Definition, and Find All Occurrences for variables in the same file. + +For example, here we Peek (`kb(editor.action.peekDefinition)`) at the definition of `--bg-color`: + +![css peek definition](images/May_2016/css-peek-definition.png) + +## Linters + +### ESLint + +The [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) now supports a "fix all problems" command. You can bind the `eslint.fixAllProblems` command to a keyboard shortcut, such as: + +```json +[ + { "key": "ctrl+shift+alt+f", "command": "eslint.fixAllProblems", + "when": "editorTextFocus" } +] +``` + +### TSLint + +The [TSLint extension](https://marketplace.visualstudio.com/items?itemName=eg2.tslint) now supports excluding files from linting ([PR #47](https://github.com/Microsoft/vscode-tslint/pull/47)) as well as quick fixes for a set of TSLint warnings ([PR #40](https://github.com/Microsoft/vscode-tslint/pull/40)). Thanks for the pull requests! + + +## Debugging + +### Control opening the Debug Console + +To provide greater control over how the internal Debug Console is revealed VS Code, we are introducing the `internalConsoleOptions` setting in `launch.json` (see [#6159](https://github.com/Microsoft/vscode/issues/6159)). This is especially useful if you are using an external terminal while debugging and you want to keep VS Code focused on your code. The possible values are: + +* `neverOpen` - VS Code will *never* open the debug console +* `openOnFirstSessionStart` - VS Code will open the debug console on the *first* debug session +* `openOnSessionStart` - VS Code will open the debug console on *every* debug session + +### Node.js Improved Stepping Performance + +We want VS Code to remain lightweight and fast so to improve the stepping experience for programs with a large number of local variables per scope, we've made the following adjustments for Node.js debugging: + +* If a scope has **more than 100 local variables**, VS Code no longer automatically auto expands that scope +* After you expand the scope manually, only the **first 100** local variables are shown + +The scope header will reflect that only the first 100 local variables are being displayed: + +![100 Local Variables](images/May_2016/many-locals.png) + +To track a variable that is not within the first 100 you must add it as a Watch expression or evaluate it in the Debug Console. + +## Extension Authoring + +### Debug extension API + +We have exposed a `vscode.startDebug` command as an extension API for the VS Code debugger component. With this, a debug session can be started programmatically either by passing the name of a launch configuration file or a complete launch configuration object: + +```javascript + let launchConfig = { + type: "node", + request: "launch", + program: "${workspaceRoot}/test.js", + cwd: "${workspaceRoot}" + }; + + vscode.commands.executeCommand('vscode.startDebug', launchConfig).then(() => { + vscode.window.showInformationMessage('Debug session started successfully'); + }, err => { + vscode.window.showInformationMessage('Error: ' + err.message); + }); +``` + +More details can be found [here](https://github.com/microsoft/vscode/issues/4615). + +### TextMate grammar injections + +Extensions can now contribute TextMate grammars that inject new rules into the existing grammars used for syntax highlighting. This makes it possible to add colorization inside string literals or comments, such as highlighting of URLs or TODO markers across multiple languages. + +```json +"grammars": [ + { + "scopeName": "source.todo", + "path": "./syntaxes/todo.tmLanguage.json", + "injectTo": [ "source.js", "source.ts" ] + } +] +``` + +### Comparing files + +We have added a new API command that allows you to use the diff-editor on two arbitrary resources like so: `commands.executeCommand('vscode.diff', uri1, uri2)` + +### Updated extension samples + +There is a new rich extension sample that walks you through _virtual documents_, _eventing_, and using _language features as commands_. Also, the preview html sample was updated: + +* [contentprovider-sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/contentprovider-sample) +* [previewhtml-sample](https://github.com/Microsoft/vscode-extension-samples/tree/master/previewhtml-sample) + +### Debug Adapter: Support a 'One' or 'All' mode of operation for controlling threads + +In a previous revision of the VS Code Debug Protocol, we had introduced a `allThreadsStopped` attribute on the `StoppedEvent`. With this attribute, a debug adapter can report back to the frontend whether only a single thread or all threads have stopped. Thanks to developer feedback, we learned that a similar attribute is necessary for the `ContinueRequest` too. + +In the version 1.9.0 of the [VS Code Debug Protocol](https://github.com/Microsoft/vscode-debugadapter-node), a boolean attribute `allThreadsContinued` has been added to the response from the `ContinueRequest`. Using this attribute, a debug adapter can report back to the UI whether only a single thread or all threads are continuing. More details can be found [here](https://github.com/Microsoft/vscode/issues/6400). + +### Language Server Protocol + +The [Language Service Protocol](https://github.com/Microsoft/vscode-languageserver-protocol) now offers support for telemetry notifications. Message tracing support has been implemented in the [node client library](https://www.npmjs.com/package/vscode-languageclient) to help tracking down problems in the server. It can be enabled via a settings `${clientName}.trace.server` where client name is the name passed when creating the `LanguageClient` instance. For example `eslint.trace.server` for the ESLint linter service. + +### Command Line Extension Management + +To make it easier to automate and configure VS Code, it is now possible to list, install, and uninstall extensions from the command line. + +Example: + +``` +code --list-extensions +code --install-extension ms-vscode.cpptools +code --uninstall-extension ms-vscode.csharp +``` + +## The Monaco Editor + +At the heart of VS Code is the "Monaco" code editor. You can find the "Monaco" editor across many Microsoft properties such as OneDrive, Azure, the TypeScript playground, and even in the F12 tools in IE and Edge. + +Our goal is to enable anyone to consume the "Monaco" editor and host it in any browser. The challenge we have today is that the editor is embedded in the `vscode` repository and the language service extensions have dependencies on client (non browser) technologies. + +The first step towards releasing the editor is [an exploration](https://github.com/alexandrudima/monaco-typescript) where the TypeScript language service has been extracted from VS Code's sources and can run on top of the standalone editor API. + +In the upcoming weeks we will continue to refine the API and automate the packaging with the goal of making the "Monaco" editor public with the June release of VS Code. + +## Notable Bug Fixes + +* [959](https://github.com/Microsoft/vscode/issues/959): Fonts become fuzzy after zooming and scrolling +* [1000](https://github.com/Microsoft/vscode/issues/1000): Slow response when system is offline +* [2717](https://github.com/Microsoft/vscode/issues/2717): "Define Keybindings" is invalidating keybindings.json +* [4541](https://github.com/Microsoft/vscode/issues/4541): Problem typing in Korean +* [5645](https://github.com/Microsoft/vscode/issues/5645): Slow call stack response for TS repository +* [5780](https://github.com/Microsoft/vscode/issues/5780): Come up with better external terminal defaults on Linux +* [6029](https://github.com/Microsoft/vscode/issues/6029): debug doesn't work on node v6 +* [6151](https://github.com/Microsoft/vscode/issues/6151): The border of scroll bar is ugly, and unclear under high dpi +* [6432](https://github.com/Microsoft/vscode/issues/6432): Unity desktop entry not installed immediately after installation +* [6525](https://github.com/Microsoft/vscode/issues/6525): Linux CLI fails to open files with spaces in filename +* [6530](https://github.com/Microsoft/vscode/issues/6530): source maps don't work if drive letter case does not match +* [6593](https://github.com/Microsoft/vscode/issues/6593): Two desktop entries appear on Ubuntu sometimes +* [6609](https://github.com/Microsoft/vscode/issues/6609): Change keybinding for 'fold all' / 'unfold all' +* [6878](https://github.com/Microsoft/vscode/issues/6878), [6916](https://github.com/Microsoft/vscode/issues/6916): Freeze/Crash when dealing with minified js files + + +These are the [closed bugs](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+label%3Abug+milestone%3A%22May+2016%22+is%3Aclosed) and these are the [closed feature requests](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+milestone%3A%22May+2016%22+is%3Aclosed+label%3Afeature-request) for the 1.2.0 update. + +## Downloads + +Downloads: [Windows](https://az764295.vo.msecnd.net/stable/809e7b30e928e0c430141b3e6abf1f63aaf55589/VSCodeSetup-stable.exe) | +[OS X](https://az764295.vo.msecnd.net/stable/809e7b30e928e0c430141b3e6abf1f63aaf55589/VSCode-darwin-stable.zip) | Linux 64-bit [.zip](https://az764295.vo.msecnd.net/stable/809e7b30e928e0c430141b3e6abf1f63aaf55589/VSCode-linux-x64-stable.zip) [.deb](https://az764295.vo.msecnd.net/stable/809e7b30e928e0c430141b3e6abf1f63aaf55589/vscode-amd64.deb) [.rpm](https://az764295.vo.msecnd.net/stable/809e7b30e928e0c430141b3e6abf1f63aaf55589/vscode-x86_64.rpm) | Linux 32-bit [.zip](https://az764295.vo.msecnd.net/stable/809e7b30e928e0c430141b3e6abf1f63aaf55589/VSCode-linux-ia32-stable.zip) [.deb](https://az764295.vo.msecnd.net/stable/809e7b30e928e0c430141b3e6abf1f63aaf55589/vscode-i386.deb) [.rpm](https://az764295.vo.msecnd.net/stable/809e7b30e928e0c430141b3e6abf1f63aaf55589/vscode-i386.rpm) + +## Thank You + +Last but certainly not least, a big *__Thank You!__* to the following folks that helped to make VS Code even better: + +* [Peng Lv (@rebornix)](https://github.com/rebornix): Add touch screen tap support for reference search. [PR #6386](https://github.com/Microsoft/vscode/pull/6386) +* [Yuki Ueda (@Ikuyadeu)](https://github.com/Ikuyadeu) + * Debt reduction in suggest [PR #6035](https://github.com/Microsoft/vscode/pull/6035) and [PR #6057](https://github.com/Microsoft/vscode/pull/6057) + * Delete the mention [PR #5786](https://github.com/Microsoft/vscode/pull/5786) +* [Richard Lasjunies (@rlasjunies)](https://github.com/rlasjunies): vscode-tslint - autofix some tslint warnings [PR #47](https://github.com/Microsoft/vscode-tslint/pull/47) +* [Gary Wilber (@Spacetech)](https://github.com/Spacetech): vscode-tslint - Ability to exclude files [PR #40](https://github.com/Microsoft/vscode-tslint/pull/40) +* [@dbillingham](https://github.com/dbillingham): [folding] Added fold and unfold recursively to foldings [PR #5721](https://github.com/Microsoft/vscode/pull/5721) +* [Brian Green (@briangreenery)](https://github.com/briangreenery): Fix small typos [PR #33](https://github.com/Microsoft/vscode-languageserver-node/pull/33) +* [Rui Lopes (@rgl)](https://github.com/rgl): Correct typos [PR #6](https://github.com/Microsoft/vscode-languageserver-protocol/pull/6) +* [Brett Cannon (@brettcannon)](https://github.com/brettcannon): Grammar tweak in a comment [PR #8](https://github.com/Microsoft/vscode-languageserver-node-example/pull/8) +* [Cody Hoover (@hoovercj)](https://github.com/hoovercj): Update launch.json [PR #10](https://github.com/Microsoft/vscode-languageserver-node-example/pull/10) +* [Yu-Hsin Hung (@hungys)](https://github.com/hungys): Fix link parsing for non-ASCII characters [PR #5293](https://github.com/Microsoft/vscode/pull/5293) +* [Denis Gladkikh (@outcoldman)](https://github.com/outcoldman): Editor improvements (Implement trim whitespaces on enter, Backspaces decreases indent) [PR #5423](https://github.com/Microsoft/vscode/pull/5423) +* [@ioklo](https://github.com/ioklo): fix Korean(and Chinese, Japanese) IME behavior [PR #5615](https://github.com/Microsoft/vscode/pull/5615) +* [aioute Gao (@aioutecism)](https://github.com/aioutecism): Fix validatePosition related bug [PR #5705](https://github.com/Microsoft/vscode/pull/5705) +* [Asuka (@Inori)](https://github.com/Inori): Add selectAllMatches command in column selection mode [PR #5715](https://github.com/Microsoft/vscode/pull/5715) + + diff --git a/release-notes/css/inproduct_releasenotes.css b/release-notes/css/inproduct_releasenotes.css new file mode 100644 index 0000000000000000000000000000000000000000..7c0b0144df7dcaebaa6512e49ad979a3ffbb7b4d --- /dev/null +++ b/release-notes/css/inproduct_releasenotes.css @@ -0,0 +1,82 @@ + +html { + font-size: 10px; +} +body { + padding-bottom: 100px; +} + +h1,h2,h3 { + font-weight: lighter; + margin-top: 2rem; + margin-bottom: 1rem; +} + +h1 { + font-size: 4rem; + margin-bottom:1.5rem; +} + +h2 { + font-size: 3rem; + margin-top: 3rem; +} + + +h3 { + font-size: 2.2rem; +} + +h4 { + font-size: 1.2rem; + text-transform: uppercase; + margin-top: 3rem; + margin-bottom: 1rem; +} + +#scroll-to-top { + position: fixed; + width: 40px; + height: 40px; + right: 25px; + bottom: 25px; + /*background-color:#0e639c;*/ + background-color:#444444; + border-radius: 50%; + cursor: pointer; + box-shadow: 1px 1px 1px rgba(0,0,0,.25); + outline: none; +} + +#scroll-to-top:hover { + background-color:#007acc; + box-shadow: 2px 2px 2px rgba(0,0,0,.25); +} + +/* Theme-specific colors */ +body.vscode-light #scroll-to-top { + background-color: #949494; +} +body.vscode-light #scroll-to-top:hover { + background-color: #007acc; +} + +body.vscode-high-contrast #scroll-to-top { + background-color: black; + border: 2px solid #6fc3df; + box-shadow: none; +} +body.vscode-high-contrast #scroll-to-top:hover { + background-color: #007acc; +} + +#scroll-to-top span.icon::before { + content: ""; + /* Chevron up icon */ + background:url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDE5LjIuMCwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCAxNiAxNiIgc3R5bGU9ImVuYWJsZS1iYWNrZ3JvdW5kOm5ldyAwIDAgMTYgMTY7IiB4bWw6c3BhY2U9InByZXNlcnZlIj4KPHN0eWxlIHR5cGU9InRleHQvY3NzIj4KCS5zdDB7ZmlsbDojRkZGRkZGO30KCS5zdDF7ZmlsbDpub25lO30KPC9zdHlsZT4KPHRpdGxlPnVwY2hldnJvbjwvdGl0bGU+CjxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik04LDUuMWwtNy4zLDcuM0wwLDExLjZsOC04bDgsOGwtMC43LDAuN0w4LDUuMXoiLz4KPHJlY3QgY2xhc3M9InN0MSIgd2lkdGg9IjE2IiBoZWlnaHQ9IjE2Ii8+Cjwvc3ZnPgo='); + width: 1.6rem; + height: 1.6rem; + position:absolute; + left: calc(50% - 1.6rem / 2); + top: calc(50% - 1.6rem / 2); +} \ No newline at end of file diff --git a/release-notes/images/0_10_0/add-to-watch.png b/release-notes/images/0_10_0/add-to-watch.png new file mode 100644 index 0000000000000000000000000000000000000000..d0e086277059845fea9c05d4277047a1a5283d96 Binary files /dev/null and b/release-notes/images/0_10_0/add-to-watch.png differ diff --git a/release-notes/images/0_10_0/colored-output.png b/release-notes/images/0_10_0/colored-output.png new file mode 100644 index 0000000000000000000000000000000000000000..b4f4352b179cfa5f76b11b55793fa8542b7e7fb7 Binary files /dev/null and b/release-notes/images/0_10_0/colored-output.png differ diff --git a/release-notes/images/0_10_0/extension-commands.png b/release-notes/images/0_10_0/extension-commands.png new file mode 100644 index 0000000000000000000000000000000000000000..d017c1bdc27e9417cb0797e0d0163fbe6ba406bf Binary files /dev/null and b/release-notes/images/0_10_0/extension-commands.png differ diff --git a/release-notes/images/0_10_0/extension-language.png b/release-notes/images/0_10_0/extension-language.png new file mode 100644 index 0000000000000000000000000000000000000000..db777dff805c613379aadedb5b3fff6452b6f1a6 Binary files /dev/null and b/release-notes/images/0_10_0/extension-language.png differ diff --git a/release-notes/images/0_10_0/hello-code.png b/release-notes/images/0_10_0/hello-code.png new file mode 100644 index 0000000000000000000000000000000000000000..85a1dd80809da6e7ca96607c3caeafe0083cc44b --- /dev/null +++ b/release-notes/images/0_10_0/hello-code.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:03db61480ecf7a2ea7e98e3d4678e01482ffc20fa5b4b8ed307aa9827e1a899a +size 110748 diff --git a/release-notes/images/0_10_0/inline-diff-view.png b/release-notes/images/0_10_0/inline-diff-view.png new file mode 100644 index 0000000000000000000000000000000000000000..a1b1ed63cf19e7927d94f9e094b762c9e453c1e5 Binary files /dev/null and b/release-notes/images/0_10_0/inline-diff-view.png differ diff --git a/release-notes/images/0_10_0/marketplace.png b/release-notes/images/0_10_0/marketplace.png new file mode 100644 index 0000000000000000000000000000000000000000..9c69c6c1cb930baf7d859f08cda959780dd9f1c7 Binary files /dev/null and b/release-notes/images/0_10_0/marketplace.png differ diff --git a/release-notes/images/0_10_0/select-debug-env.png b/release-notes/images/0_10_0/select-debug-env.png new file mode 100644 index 0000000000000000000000000000000000000000..917efa152a249f63122ccf49dbe40ce9f15df150 Binary files /dev/null and b/release-notes/images/0_10_0/select-debug-env.png differ diff --git a/release-notes/images/0_10_0/theme-0-10-0.png b/release-notes/images/0_10_0/theme-0-10-0.png new file mode 100644 index 0000000000000000000000000000000000000000..1f0e1be354705e12706b08e5e10d3e0b706145b3 Binary files /dev/null and b/release-notes/images/0_10_0/theme-0-10-0.png differ diff --git a/release-notes/images/0_10_0/theme-0-9-0.png b/release-notes/images/0_10_0/theme-0-9-0.png new file mode 100644 index 0000000000000000000000000000000000000000..36e45275a29efb642fc2baadb0680ff28e5ad68e Binary files /dev/null and b/release-notes/images/0_10_0/theme-0-9-0.png differ diff --git a/release-notes/images/0_10_0/yo-code.png b/release-notes/images/0_10_0/yo-code.png new file mode 100644 index 0000000000000000000000000000000000000000..4247a9eec459b37e52b8c7ec09a5286e9ddc87fb Binary files /dev/null and b/release-notes/images/0_10_0/yo-code.png differ diff --git a/release-notes/images/0_3_0/BlockComments.png b/release-notes/images/0_3_0/BlockComments.png new file mode 100644 index 0000000000000000000000000000000000000000..266189e2aaa5bbf3eb234c246d863c34dfeeff6b Binary files /dev/null and b/release-notes/images/0_3_0/BlockComments.png differ diff --git a/release-notes/images/0_3_0/ChineseLoremIpsum.png b/release-notes/images/0_3_0/ChineseLoremIpsum.png new file mode 100644 index 0000000000000000000000000000000000000000..99343b3254f245d6aa1808146a14a41c2da25f1d Binary files /dev/null and b/release-notes/images/0_3_0/ChineseLoremIpsum.png differ diff --git a/release-notes/images/0_3_0/CopyPath.gif b/release-notes/images/0_3_0/CopyPath.gif new file mode 100644 index 0000000000000000000000000000000000000000..c03bb2ef94a171ee7bcd43bcb584761a29b730ad Binary files /dev/null and b/release-notes/images/0_3_0/CopyPath.gif differ diff --git a/release-notes/images/0_3_0/CopyPathPalette.png b/release-notes/images/0_3_0/CopyPathPalette.png new file mode 100644 index 0000000000000000000000000000000000000000..0d55ac079d9b9d1622b1a8e69ec714c1e90413ae Binary files /dev/null and b/release-notes/images/0_3_0/CopyPathPalette.png differ diff --git a/release-notes/images/0_3_0/DebugVisualization.png b/release-notes/images/0_3_0/DebugVisualization.png new file mode 100644 index 0000000000000000000000000000000000000000..fa545cf694f08875959dfe9fd4d1fa52ed1768d9 Binary files /dev/null and b/release-notes/images/0_3_0/DebugVisualization.png differ diff --git a/release-notes/images/0_3_0/EncodingClicked.png b/release-notes/images/0_3_0/EncodingClicked.png new file mode 100644 index 0000000000000000000000000000000000000000..7a8b1df6e1b4a3aeacd0c44417de23822db0f2a0 Binary files /dev/null and b/release-notes/images/0_3_0/EncodingClicked.png differ diff --git a/release-notes/images/0_3_0/EncodingSelection.png b/release-notes/images/0_3_0/EncodingSelection.png new file mode 100644 index 0000000000000000000000000000000000000000..26010d05b7ebfdefead9941b6c172a8fc7bd7406 Binary files /dev/null and b/release-notes/images/0_3_0/EncodingSelection.png differ diff --git a/release-notes/images/0_3_0/FileEncoding.png b/release-notes/images/0_3_0/FileEncoding.png new file mode 100644 index 0000000000000000000000000000000000000000..ef3237c239ffaf24c028b58bbc837c676a998c99 Binary files /dev/null and b/release-notes/images/0_3_0/FileEncoding.png differ diff --git a/release-notes/images/0_3_0/FilesEncodingSetting.png b/release-notes/images/0_3_0/FilesEncodingSetting.png new file mode 100644 index 0000000000000000000000000000000000000000..0a0ee48cf595a7424b124caba7770abe001fc40e Binary files /dev/null and b/release-notes/images/0_3_0/FilesEncodingSetting.png differ diff --git a/release-notes/images/0_3_0/WrappingIndentIndent.png b/release-notes/images/0_3_0/WrappingIndentIndent.png new file mode 100644 index 0000000000000000000000000000000000000000..9dfd3402df96ce115f9142c55a66b6a29f490a9f Binary files /dev/null and b/release-notes/images/0_3_0/WrappingIndentIndent.png differ diff --git a/release-notes/images/0_3_0/WrappingIndentNone.png b/release-notes/images/0_3_0/WrappingIndentNone.png new file mode 100644 index 0000000000000000000000000000000000000000..f286ea30972b5ad2e20c8dc4cfdee25e14245fd5 Binary files /dev/null and b/release-notes/images/0_3_0/WrappingIndentNone.png differ diff --git a/release-notes/images/0_3_0/WrappingIndentSame.png b/release-notes/images/0_3_0/WrappingIndentSame.png new file mode 100644 index 0000000000000000000000000000000000000000..9955c1663bf5f98fc8557c2187744ca8117494f5 Binary files /dev/null and b/release-notes/images/0_3_0/WrappingIndentSame.png differ diff --git a/release-notes/images/0_3_0/compare.png b/release-notes/images/0_3_0/compare.png new file mode 100644 index 0000000000000000000000000000000000000000..a321ee6c38414cc081a850620355d3361b86c9c6 Binary files /dev/null and b/release-notes/images/0_3_0/compare.png differ diff --git a/release-notes/images/0_3_0/expandselection.gif b/release-notes/images/0_3_0/expandselection.gif new file mode 100644 index 0000000000000000000000000000000000000000..8d411643dbd2d13fa3787cfbdbe1f42bd3b3a789 Binary files /dev/null and b/release-notes/images/0_3_0/expandselection.gif differ diff --git a/release-notes/images/0_3_0/settingserrors.png b/release-notes/images/0_3_0/settingserrors.png new file mode 100644 index 0000000000000000000000000000000000000000..67ab59944679cbeb2d6452f6955a3303eedb3cf8 Binary files /dev/null and b/release-notes/images/0_3_0/settingserrors.png differ diff --git a/release-notes/images/0_5_0/CredentialPrompt.png b/release-notes/images/0_5_0/CredentialPrompt.png new file mode 100644 index 0000000000000000000000000000000000000000..ed65ba78546fa6b38eff7aa54ff21625734d8b5d Binary files /dev/null and b/release-notes/images/0_5_0/CredentialPrompt.png differ diff --git a/release-notes/images/0_5_0/GitMultiSelect.gif b/release-notes/images/0_5_0/GitMultiSelect.gif new file mode 100644 index 0000000000000000000000000000000000000000..4a99f1e689be864b2876c6dc0443474a9a4095be Binary files /dev/null and b/release-notes/images/0_5_0/GitMultiSelect.gif differ diff --git a/release-notes/images/0_5_0/HidingDerivedResources.png b/release-notes/images/0_5_0/HidingDerivedResources.png new file mode 100644 index 0000000000000000000000000000000000000000..8b8dbb71a8a4b5c333e5f7ea965874592a3b4840 Binary files /dev/null and b/release-notes/images/0_5_0/HidingDerivedResources.png differ diff --git a/release-notes/images/0_5_0/JsconfigJson.png b/release-notes/images/0_5_0/JsconfigJson.png new file mode 100644 index 0000000000000000000000000000000000000000..cd7feda0586ce1622a078a248e9cebee057e69f6 Binary files /dev/null and b/release-notes/images/0_5_0/JsconfigJson.png differ diff --git a/release-notes/images/0_5_0/MultilineCommit.png b/release-notes/images/0_5_0/MultilineCommit.png new file mode 100644 index 0000000000000000000000000000000000000000..dee8895d8b888142a7ccbfe00d6478f3f1f0cb43 Binary files /dev/null and b/release-notes/images/0_5_0/MultilineCommit.png differ diff --git a/release-notes/images/0_5_0/NodeBreakpoints.png b/release-notes/images/0_5_0/NodeBreakpoints.png new file mode 100644 index 0000000000000000000000000000000000000000..49176e391cbafa51b6be38cb6c8f5bea1537091c Binary files /dev/null and b/release-notes/images/0_5_0/NodeBreakpoints.png differ diff --git a/release-notes/images/0_5_0/SearchPatterns.png b/release-notes/images/0_5_0/SearchPatterns.png new file mode 100644 index 0000000000000000000000000000000000000000..7b576bf2347e5eb20325ba67d39219a25d2a5c3f Binary files /dev/null and b/release-notes/images/0_5_0/SearchPatterns.png differ diff --git a/release-notes/images/0_5_0/ShebangColoring.png b/release-notes/images/0_5_0/ShebangColoring.png new file mode 100644 index 0000000000000000000000000000000000000000..2c9c40a39d0734b22987b452af374ab753a3c5d5 Binary files /dev/null and b/release-notes/images/0_5_0/ShebangColoring.png differ diff --git a/release-notes/images/0_5_0/ToggleActiveBPs.png b/release-notes/images/0_5_0/ToggleActiveBPs.png new file mode 100644 index 0000000000000000000000000000000000000000..a7285b74de6d243228c40a367cf3717c1fd48370 Binary files /dev/null and b/release-notes/images/0_5_0/ToggleActiveBPs.png differ diff --git a/release-notes/images/0_5_0/WatchExpressions.png b/release-notes/images/0_5_0/WatchExpressions.png new file mode 100644 index 0000000000000000000000000000000000000000..928e5b2a0d6ead51c79fb5bfe4fc2a58d9a07c59 Binary files /dev/null and b/release-notes/images/0_5_0/WatchExpressions.png differ diff --git a/release-notes/images/0_7_0/DebugChunkedArrays.png b/release-notes/images/0_7_0/DebugChunkedArrays.png new file mode 100644 index 0000000000000000000000000000000000000000..de1b4c3d1f15c40b49b3c55c2ff64a86b6110859 Binary files /dev/null and b/release-notes/images/0_7_0/DebugChunkedArrays.png differ diff --git a/release-notes/images/0_7_0/PHPSnip.png b/release-notes/images/0_7_0/PHPSnip.png new file mode 100644 index 0000000000000000000000000000000000000000..58030599908a72d585e72117e55f475641c230d2 Binary files /dev/null and b/release-notes/images/0_7_0/PHPSnip.png differ diff --git a/release-notes/images/0_7_0/QuickFixOnMarker.png b/release-notes/images/0_7_0/QuickFixOnMarker.png new file mode 100644 index 0000000000000000000000000000000000000000..fc9526d4005857eadc73d648df76eb2b1854b654 Binary files /dev/null and b/release-notes/images/0_7_0/QuickFixOnMarker.png differ diff --git a/release-notes/images/0_7_0/QuickFixOnSelection.png b/release-notes/images/0_7_0/QuickFixOnSelection.png new file mode 100644 index 0000000000000000000000000000000000000000..bd0f6340a7c1fd89218455492a449c61e50992e2 Binary files /dev/null and b/release-notes/images/0_7_0/QuickFixOnSelection.png differ diff --git a/release-notes/images/0_8_0/colorthemes.gif b/release-notes/images/0_8_0/colorthemes.gif new file mode 100644 index 0000000000000000000000000000000000000000..a9fa892028499baac199e6167d0a18958ada39a2 --- /dev/null +++ b/release-notes/images/0_8_0/colorthemes.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:19ffeb2ef751cfd110248431ff83a2eae94fdb9d03d4dfeb4cce2e189cdf8609 +size 319750 diff --git a/release-notes/images/0_8_0/debugconsole.png b/release-notes/images/0_8_0/debugconsole.png new file mode 100644 index 0000000000000000000000000000000000000000..d3a582bee5bd748b13bc49a6ab5f6a33874753eb Binary files /dev/null and b/release-notes/images/0_8_0/debugconsole.png differ diff --git a/release-notes/images/0_9_0/antlanguage.png b/release-notes/images/0_9_0/antlanguage.png new file mode 100644 index 0000000000000000000000000000000000000000..4c63597db75fc3b77b2613b45ab50df13b152c73 Binary files /dev/null and b/release-notes/images/0_9_0/antlanguage.png differ diff --git a/release-notes/images/0_9_0/debugconsole.png b/release-notes/images/0_9_0/debugconsole.png new file mode 100644 index 0000000000000000000000000000000000000000..5be9ee3a98681c30cd0cbc21aec4b7839a971289 Binary files /dev/null and b/release-notes/images/0_9_0/debugconsole.png differ diff --git a/release-notes/images/0_9_0/lang-status.png b/release-notes/images/0_9_0/lang-status.png new file mode 100644 index 0000000000000000000000000000000000000000..f3876cc3682dba4f722d2b1db4933d43feebc7c4 Binary files /dev/null and b/release-notes/images/0_9_0/lang-status.png differ diff --git a/release-notes/images/0_9_0/mytheme.png b/release-notes/images/0_9_0/mytheme.png new file mode 100644 index 0000000000000000000000000000000000000000..1a3673ff61fe0bb5f9ddf76baac2b56331717585 Binary files /dev/null and b/release-notes/images/0_9_0/mytheme.png differ diff --git a/release-notes/images/0_9_0/openpreviewside.png b/release-notes/images/0_9_0/openpreviewside.png new file mode 100644 index 0000000000000000000000000000000000000000..fb32cc6e4e7b24974f132605a20530292158628a Binary files /dev/null and b/release-notes/images/0_9_0/openpreviewside.png differ diff --git a/release-notes/images/0_9_0/unityshadercolorization.png b/release-notes/images/0_9_0/unityshadercolorization.png new file mode 100644 index 0000000000000000000000000000000000000000..6633e872804eec2310406581b69fe33dbca08db6 Binary files /dev/null and b/release-notes/images/0_9_0/unityshadercolorization.png differ diff --git a/release-notes/images/0_9_0/yocode.png b/release-notes/images/0_9_0/yocode.png new file mode 100644 index 0000000000000000000000000000000000000000..266e71bb2a954c28cf4612865c5f69b244449292 Binary files /dev/null and b/release-notes/images/0_9_0/yocode.png differ diff --git a/release-notes/images/0_9_0/yocodelanguage.png b/release-notes/images/0_9_0/yocodelanguage.png new file mode 100644 index 0000000000000000000000000000000000000000..d9e942b787f1a30eb782c1db80263b25531a6948 Binary files /dev/null and b/release-notes/images/0_9_0/yocodelanguage.png differ diff --git a/release-notes/images/0_9_0/yocodetheme.png b/release-notes/images/0_9_0/yocodetheme.png new file mode 100644 index 0000000000000000000000000000000000000000..e42517ccdd1813b5cff4abb626a2d6b4d0930f6b Binary files /dev/null and b/release-notes/images/0_9_0/yocodetheme.png differ diff --git a/release-notes/images/1_10/apt-repo.jpg b/release-notes/images/1_10/apt-repo.jpg new file mode 100644 index 0000000000000000000000000000000000000000..06dae49730886620c0e508d820e6cc0d3d047142 Binary files /dev/null and b/release-notes/images/1_10/apt-repo.jpg differ diff --git a/release-notes/images/1_10/column-breakpoints.gif b/release-notes/images/1_10/column-breakpoints.gif new file mode 100644 index 0000000000000000000000000000000000000000..a7df609afb8eabc5ee1d91da37f49fd6b6cfb98f --- /dev/null +++ b/release-notes/images/1_10/column-breakpoints.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e41a2cb73d60aea9f4df6f4927eb15ee68f8ad90bf828eb483f8a3912523383a +size 168489 diff --git a/release-notes/images/1_10/copy-with-syntax-highlighting.gif b/release-notes/images/1_10/copy-with-syntax-highlighting.gif new file mode 100644 index 0000000000000000000000000000000000000000..7a9bfb48c80b6815498302c66c24038ecb0623b2 --- /dev/null +++ b/release-notes/images/1_10/copy-with-syntax-highlighting.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:782feb4b352daf2cef9e37e00b21c946cd6a21b0f97512631ddf1a14cbef0373 +size 822438 diff --git a/release-notes/images/1_10/drag-and-drop.gif b/release-notes/images/1_10/drag-and-drop.gif new file mode 100644 index 0000000000000000000000000000000000000000..87164e01ae4ef10987aaac55894eb984378a7ed7 --- /dev/null +++ b/release-notes/images/1_10/drag-and-drop.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6f1ae8f286a6ffb02a396bd7f1397a1ba879037c17b1b96184c6fe9b21ec3295 +size 897818 diff --git a/release-notes/images/1_10/exception-widget.png b/release-notes/images/1_10/exception-widget.png new file mode 100644 index 0000000000000000000000000000000000000000..a6b2a2069f52e600156acb988b5af37531037948 Binary files /dev/null and b/release-notes/images/1_10/exception-widget.png differ diff --git a/release-notes/images/1_10/html-document-symbols.png b/release-notes/images/1_10/html-document-symbols.png new file mode 100644 index 0000000000000000000000000000000000000000..6474f3605f942c652069bd52925a53f5cddc5887 Binary files /dev/null and b/release-notes/images/1_10/html-document-symbols.png differ diff --git a/release-notes/images/1_10/jsdoc-autofill.gif b/release-notes/images/1_10/jsdoc-autofill.gif new file mode 100644 index 0000000000000000000000000000000000000000..686b0275f34eafb07d784fe915cdd5d039cab1bd --- /dev/null +++ b/release-notes/images/1_10/jsdoc-autofill.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:713ae8ae9746f6249a3839d549111cf305645626343f0c00dda9e88a85488aa9 +size 669662 diff --git a/release-notes/images/1_10/launch-keyboard.gif b/release-notes/images/1_10/launch-keyboard.gif new file mode 100644 index 0000000000000000000000000000000000000000..d35efd5bb8ad91eadaf2c0167a51e18ae5c93bdf --- /dev/null +++ b/release-notes/images/1_10/launch-keyboard.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bf8922845490407b12d0f5361ad6f35115355c2d3d1db46e38cf120ed61ffe1c +size 114538 diff --git a/release-notes/images/1_10/menu.png b/release-notes/images/1_10/menu.png new file mode 100644 index 0000000000000000000000000000000000000000..9ac0d037630986053ca1e66b9e801230045a2f3d Binary files /dev/null and b/release-notes/images/1_10/menu.png differ diff --git a/release-notes/images/1_10/minimap-blocks-scroll.gif b/release-notes/images/1_10/minimap-blocks-scroll.gif new file mode 100644 index 0000000000000000000000000000000000000000..9dee63664890716eca845432999975c179ac57a1 --- /dev/null +++ b/release-notes/images/1_10/minimap-blocks-scroll.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2d7128a316d8fb28cfce80f8d63207d106f35f5bbdabdd6d7db0800cc29990e3 +size 2911975 diff --git a/release-notes/images/1_10/minimap.png b/release-notes/images/1_10/minimap.png new file mode 100644 index 0000000000000000000000000000000000000000..fc33e7e3812dbf316633393f26ffd818e35fd7cb --- /dev/null +++ b/release-notes/images/1_10/minimap.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d1cdd9a94420d1a473791962839b020d7abfca48e51473932a3368e17ecdaa19 +size 687021 diff --git a/release-notes/images/1_10/performanto.png b/release-notes/images/1_10/performanto.png new file mode 100644 index 0000000000000000000000000000000000000000..6222c240d7380366abe312fd0b8d5d5aa7f31394 Binary files /dev/null and b/release-notes/images/1_10/performanto.png differ diff --git a/release-notes/images/1_10/release-highlights.png b/release-notes/images/1_10/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..8ea95c91ed6b8c91d0c57ec83219e15e2101ddfc Binary files /dev/null and b/release-notes/images/1_10/release-highlights.png differ diff --git a/release-notes/images/1_10/search-results-count.png b/release-notes/images/1_10/search-results-count.png new file mode 100644 index 0000000000000000000000000000000000000000..a4909c89cdc17c61404c600ba6c3c32ec247b284 Binary files /dev/null and b/release-notes/images/1_10/search-results-count.png differ diff --git a/release-notes/images/1_10/terminal-link.png b/release-notes/images/1_10/terminal-link.png new file mode 100644 index 0000000000000000000000000000000000000000..d71d882115ca370a053edcbfc72c4385ec34a20a Binary files /dev/null and b/release-notes/images/1_10/terminal-link.png differ diff --git a/release-notes/images/1_11/abyss-theme.png b/release-notes/images/1_11/abyss-theme.png new file mode 100644 index 0000000000000000000000000000000000000000..c30b552327ee8988fa598aa16b4c264f5cb4dc33 --- /dev/null +++ b/release-notes/images/1_11/abyss-theme.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9d8e92e147bdf8245d21348715d95ba59aee9d337f3989e5cafdd41c721d9637 +size 153584 diff --git a/release-notes/images/1_11/async-stack-after.png b/release-notes/images/1_11/async-stack-after.png new file mode 100644 index 0000000000000000000000000000000000000000..bfb79115b973492ef8129892f5b9a63878761948 Binary files /dev/null and b/release-notes/images/1_11/async-stack-after.png differ diff --git a/release-notes/images/1_11/async-stack-before.png b/release-notes/images/1_11/async-stack-before.png new file mode 100644 index 0000000000000000000000000000000000000000..2f85c7c01145e9a50622f7328689b48e6635a98c Binary files /dev/null and b/release-notes/images/1_11/async-stack-before.png differ diff --git a/release-notes/images/1_11/color-settings.gif b/release-notes/images/1_11/color-settings.gif new file mode 100644 index 0000000000000000000000000000000000000000..2e917a910eccaf4453ee20700d86c72752a0304e --- /dev/null +++ b/release-notes/images/1_11/color-settings.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b717a1958bc6fd4736208e7dba02fd056b1ce3318629dc6f6711cf2b06095121 +size 721492 diff --git a/release-notes/images/1_11/column-breakpoints.png b/release-notes/images/1_11/column-breakpoints.png new file mode 100644 index 0000000000000000000000000000000000000000..acdbca76ca3de56fa02b768bd95946b19d04a4d6 Binary files /dev/null and b/release-notes/images/1_11/column-breakpoints.png differ diff --git a/release-notes/images/1_11/config-exceptions.gif b/release-notes/images/1_11/config-exceptions.gif new file mode 100644 index 0000000000000000000000000000000000000000..008807d90996a73b4224381a772a0adff8ea767a --- /dev/null +++ b/release-notes/images/1_11/config-exceptions.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:231b85fe5588e790f793f60819263d8d45f5b62e479e5bf5ea1309ca1b636c17 +size 3579788 diff --git a/release-notes/images/1_11/debug-menu.png b/release-notes/images/1_11/debug-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..cfb267a67c1e41c34d5b1942cee042ca481e43de Binary files /dev/null and b/release-notes/images/1_11/debug-menu.png differ diff --git a/release-notes/images/1_11/dnd.gif b/release-notes/images/1_11/dnd.gif new file mode 100644 index 0000000000000000000000000000000000000000..670689fe590a04a204e84048a10a33a67d28e080 Binary files /dev/null and b/release-notes/images/1_11/dnd.gif differ diff --git a/release-notes/images/1_11/encoding.png b/release-notes/images/1_11/encoding.png new file mode 100644 index 0000000000000000000000000000000000000000..8e648817b91fdf139015ad8a566d1a8ffddd0060 Binary files /dev/null and b/release-notes/images/1_11/encoding.png differ diff --git a/release-notes/images/1_11/exception-peekui.png b/release-notes/images/1_11/exception-peekui.png new file mode 100644 index 0000000000000000000000000000000000000000..419346ff7bb909b993ab6115f697332a4440d947 --- /dev/null +++ b/release-notes/images/1_11/exception-peekui.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:12ba49d2b18810283485a29648a6708fa5aa3660420bda230434cdc54e4ab3a3 +size 108132 diff --git a/release-notes/images/1_11/file-deleted.png b/release-notes/images/1_11/file-deleted.png new file mode 100644 index 0000000000000000000000000000000000000000..15b9d7a7a47d6dc3016e29ac4e4040bcba0a61e4 Binary files /dev/null and b/release-notes/images/1_11/file-deleted.png differ diff --git a/release-notes/images/1_11/fuzzy-score.png b/release-notes/images/1_11/fuzzy-score.png new file mode 100644 index 0000000000000000000000000000000000000000..a26c4d32126079148cc1fbe72d86d0f8cc0ce543 Binary files /dev/null and b/release-notes/images/1_11/fuzzy-score.png differ diff --git a/release-notes/images/1_11/keyboard-shortcuts.gif b/release-notes/images/1_11/keyboard-shortcuts.gif new file mode 100644 index 0000000000000000000000000000000000000000..b5f391a9a95223b81f0925d20d245c8b35179fa6 --- /dev/null +++ b/release-notes/images/1_11/keyboard-shortcuts.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:571c00c05269ca066de994d27c7618b22c0872bb42b2eb4d2a743a7c91ceea36 +size 1111409 diff --git a/release-notes/images/1_11/loaded-scripts.gif b/release-notes/images/1_11/loaded-scripts.gif new file mode 100644 index 0000000000000000000000000000000000000000..84bbab0f53b6540c07f0ee8b864f52e811f19889 --- /dev/null +++ b/release-notes/images/1_11/loaded-scripts.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8755135c7cc5c11d109a7fc582a595e670d6984dd45ade3b058de155af24a7f0 +size 4603858 diff --git a/release-notes/images/1_11/panel.gif b/release-notes/images/1_11/panel.gif new file mode 100644 index 0000000000000000000000000000000000000000..d18e45c23049f77408183197f7a0e69a16d9825e --- /dev/null +++ b/release-notes/images/1_11/panel.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5f6ef48578e9f4124f2084436a725e36ae5937a73e69ceae398c2d94b8b1f71f +size 1042767 diff --git a/release-notes/images/1_11/release-highlights.png b/release-notes/images/1_11/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..c7ab82be45b082431a30eb74d5ff48f5cd6015e8 Binary files /dev/null and b/release-notes/images/1_11/release-highlights.png differ diff --git a/release-notes/images/1_11/scm-provider-icon.png b/release-notes/images/1_11/scm-provider-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..1027e0aecbff1c1b9bf6f2f0cc92a994517fa3c0 Binary files /dev/null and b/release-notes/images/1_11/scm-provider-icon.png differ diff --git a/release-notes/images/1_11/search-viewlet.png b/release-notes/images/1_11/search-viewlet.png new file mode 100644 index 0000000000000000000000000000000000000000..f38be947364babaca2077e3ad5e3978b7a347aaf Binary files /dev/null and b/release-notes/images/1_11/search-viewlet.png differ diff --git a/release-notes/images/1_11/terminal-link-hint.png b/release-notes/images/1_11/terminal-link-hint.png new file mode 100644 index 0000000000000000000000000000000000000000..abcf5151dc5678eb48f18e40c5e6f4fd3c499247 Binary files /dev/null and b/release-notes/images/1_11/terminal-link-hint.png differ diff --git a/release-notes/images/1_11/terminal-shell-selector.png b/release-notes/images/1_11/terminal-shell-selector.png new file mode 100644 index 0000000000000000000000000000000000000000..41f1c3c2a745c61cff52b4404141e3e1a1d19e24 Binary files /dev/null and b/release-notes/images/1_11/terminal-shell-selector.png differ diff --git a/release-notes/images/1_11/terminal-workspace-warn.png b/release-notes/images/1_11/terminal-workspace-warn.png new file mode 100644 index 0000000000000000000000000000000000000000..82538121163ca792bed2833cf10ea915e764b2f0 Binary files /dev/null and b/release-notes/images/1_11/terminal-workspace-warn.png differ diff --git a/release-notes/images/1_11/ts-implementations-lens-expanded.png b/release-notes/images/1_11/ts-implementations-lens-expanded.png new file mode 100644 index 0000000000000000000000000000000000000000..36d5d6a30ec0722a5d65e5e7f51d41d95ae31276 Binary files /dev/null and b/release-notes/images/1_11/ts-implementations-lens-expanded.png differ diff --git a/release-notes/images/1_11/ts-implementations-lens.png b/release-notes/images/1_11/ts-implementations-lens.png new file mode 100644 index 0000000000000000000000000000000000000000..02064f047c7c26bbdf0d710c01e58824bcdce3c6 Binary files /dev/null and b/release-notes/images/1_11/ts-implementations-lens.png differ diff --git a/release-notes/images/1_12/column-breakpoints.gif b/release-notes/images/1_12/column-breakpoints.gif new file mode 100644 index 0000000000000000000000000000000000000000..46fe03e5ca0baee0895566c51e65bcbe03ce41ac --- /dev/null +++ b/release-notes/images/1_12/column-breakpoints.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9bd41eff4fc8b3d0e048f7bd3a3d1aac7c00ffd563b7dc9cbadd41750821334c +size 171963 diff --git a/release-notes/images/1_12/completions-dynamic-sort.gif b/release-notes/images/1_12/completions-dynamic-sort.gif new file mode 100644 index 0000000000000000000000000000000000000000..381b00a8380ff069c9971c7790c711f57d4e516c --- /dev/null +++ b/release-notes/images/1_12/completions-dynamic-sort.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:455a4c65f6e2438f5fff8c8709041ba66e29d521480025121357f4f5795f12b0 +size 946477 diff --git a/release-notes/images/1_12/edit-watch.png b/release-notes/images/1_12/edit-watch.png new file mode 100644 index 0000000000000000000000000000000000000000..92fe3e7b9afdaeda7c7433bc95d174bf93e10bec Binary files /dev/null and b/release-notes/images/1_12/edit-watch.png differ diff --git a/release-notes/images/1_12/keyboard-shortcuts-editor.gif b/release-notes/images/1_12/keyboard-shortcuts-editor.gif new file mode 100644 index 0000000000000000000000000000000000000000..1063356a5060054d56ddfbc021c314aa49e1508b --- /dev/null +++ b/release-notes/images/1_12/keyboard-shortcuts-editor.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8de5df0909f59e3d9a75273b131a6ea55d393953b342d1a9a82c250d23b53fa9 +size 2895769 diff --git a/release-notes/images/1_12/native-tabs.gif b/release-notes/images/1_12/native-tabs.gif new file mode 100644 index 0000000000000000000000000000000000000000..67d2d2e1eb25e2f88d343c4897309f5e7c9f6f6b --- /dev/null +++ b/release-notes/images/1_12/native-tabs.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:49b0001ed15e5dc20e209162244cff8b2091b2cfff47a6d83905de4516b1666e +size 7495119 diff --git a/release-notes/images/1_12/promise-reject-option.png b/release-notes/images/1_12/promise-reject-option.png new file mode 100644 index 0000000000000000000000000000000000000000..8593a959a4447742a440a48f4077658fb3c23627 Binary files /dev/null and b/release-notes/images/1_12/promise-reject-option.png differ diff --git a/release-notes/images/1_12/release-highlights.png b/release-notes/images/1_12/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..a74288a866b1f12f5b92f236726a8c7b555ae741 Binary files /dev/null and b/release-notes/images/1_12/release-highlights.png differ diff --git a/release-notes/images/1_12/terminal-line-col-link.gif b/release-notes/images/1_12/terminal-line-col-link.gif new file mode 100644 index 0000000000000000000000000000000000000000..69b0db625989d1f6606f0a494b3d1c7b68a98f20 --- /dev/null +++ b/release-notes/images/1_12/terminal-line-col-link.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e7d71699b2b94955be65a6355461a3f5b9a4a1c4da0cb405c533bfb5f30497b9 +size 105617 diff --git a/release-notes/images/1_12/theme-activitybar.gif b/release-notes/images/1_12/theme-activitybar.gif new file mode 100644 index 0000000000000000000000000000000000000000..9d8d09aec8723eb163fe1fa9fb31f7def3643d1e --- /dev/null +++ b/release-notes/images/1_12/theme-activitybar.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6aac6a5f681ad109f4b7062c8e643f899a789597a47015ce6b36db4d6ec3091e +size 2217617 diff --git a/release-notes/images/1_12/theme-generator.png b/release-notes/images/1_12/theme-generator.png new file mode 100644 index 0000000000000000000000000000000000000000..521b5035fecdd731dc8e3ae374f634dc76194dda --- /dev/null +++ b/release-notes/images/1_12/theme-generator.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f5a00cc2de8836efaeef37c02f75528721fe54c00d39997adc5a58c1754b2d6b +size 103864 diff --git a/release-notes/images/1_12/theme-kimbie-dark.png b/release-notes/images/1_12/theme-kimbie-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..d3f43641e92938d5bd2ea2ed1ed564a15ed6a1af Binary files /dev/null and b/release-notes/images/1_12/theme-kimbie-dark.png differ diff --git a/release-notes/images/1_12/theme-solarized-light.png b/release-notes/images/1_12/theme-solarized-light.png new file mode 100644 index 0000000000000000000000000000000000000000..d0a8d7b944fcbecffd9857ca1dcef8ad79faeb48 Binary files /dev/null and b/release-notes/images/1_12/theme-solarized-light.png differ diff --git a/release-notes/images/1_12/theme-tomorrow-blue.png b/release-notes/images/1_12/theme-tomorrow-blue.png new file mode 100644 index 0000000000000000000000000000000000000000..df90b9245523291c1f31352067c7e92bb3cb567a Binary files /dev/null and b/release-notes/images/1_12/theme-tomorrow-blue.png differ diff --git a/release-notes/images/1_12/toggle-skip-file.png b/release-notes/images/1_12/toggle-skip-file.png new file mode 100644 index 0000000000000000000000000000000000000000..806ff000e4e5dcc7c682d73635b249cfc76e2a8b Binary files /dev/null and b/release-notes/images/1_12/toggle-skip-file.png differ diff --git a/release-notes/images/1_12/ts-checkjs-example.gif b/release-notes/images/1_12/ts-checkjs-example.gif new file mode 100644 index 0000000000000000000000000000000000000000..754b0cb95e747fd1eb17fb810327a140d0db2a4d --- /dev/null +++ b/release-notes/images/1_12/ts-checkjs-example.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:99174e3201f938c8e94d7b17de3844b6a782b41b86ad4bcfea8ee066a039446f +size 2408672 diff --git a/release-notes/images/1_13/additional-scm-providers.png b/release-notes/images/1_13/additional-scm-providers.png new file mode 100644 index 0000000000000000000000000000000000000000..5380ab73466458489e3738e6719dd37f30543ab0 Binary files /dev/null and b/release-notes/images/1_13/additional-scm-providers.png differ diff --git a/release-notes/images/1_13/bot-closes-needs-more-info.png b/release-notes/images/1_13/bot-closes-needs-more-info.png new file mode 100644 index 0000000000000000000000000000000000000000..fd6606e360bdd9bceadaf1756bfea9c93581803e Binary files /dev/null and b/release-notes/images/1_13/bot-closes-needs-more-info.png differ diff --git a/release-notes/images/1_13/bot-labels-insiders.png b/release-notes/images/1_13/bot-labels-insiders.png new file mode 100644 index 0000000000000000000000000000000000000000..6d42478607f4b280abfe5e0f8fe7e1f2abe57afe Binary files /dev/null and b/release-notes/images/1_13/bot-labels-insiders.png differ diff --git a/release-notes/images/1_13/copy-all.png b/release-notes/images/1_13/copy-all.png new file mode 100644 index 0000000000000000000000000000000000000000..88d4c1be65a3eb211d3e3848b59d287bb2e20e78 Binary files /dev/null and b/release-notes/images/1_13/copy-all.png differ diff --git a/release-notes/images/1_13/emmet.gif b/release-notes/images/1_13/emmet.gif new file mode 100644 index 0000000000000000000000000000000000000000..a4fa85920bcfa02f3e5fc1b6f007149eee9945e4 --- /dev/null +++ b/release-notes/images/1_13/emmet.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fde011cddc1cdd8c5a121470a1a865a08ef84e273e22ceb4eda08ed3fbd017dc +size 197408 diff --git a/release-notes/images/1_13/exception-link-detection.png b/release-notes/images/1_13/exception-link-detection.png new file mode 100644 index 0000000000000000000000000000000000000000..5db28631dd8660989cb3b44dd95435ba890c3ca3 Binary files /dev/null and b/release-notes/images/1_13/exception-link-detection.png differ diff --git a/release-notes/images/1_13/extensions-actions.png b/release-notes/images/1_13/extensions-actions.png new file mode 100644 index 0000000000000000000000000000000000000000..68a54837b30ca89533ca32afec2c7d62f905fca3 Binary files /dev/null and b/release-notes/images/1_13/extensions-actions.png differ diff --git a/release-notes/images/1_13/go-menu.png b/release-notes/images/1_13/go-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..9913feeff1de97b312275a82e27904958f8a30d7 Binary files /dev/null and b/release-notes/images/1_13/go-menu.png differ diff --git a/release-notes/images/1_13/high-contrast.png b/release-notes/images/1_13/high-contrast.png new file mode 100644 index 0000000000000000000000000000000000000000..74d489f6a58bf4792a038202530151c95a65055e --- /dev/null +++ b/release-notes/images/1_13/high-contrast.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c732c8578d02ca08369f059fec1eefc39e38e9dd56a68ef1c9a76e899463cfb5 +size 218661 diff --git a/release-notes/images/1_13/jsdocs.png b/release-notes/images/1_13/jsdocs.png new file mode 100644 index 0000000000000000000000000000000000000000..72f547ba17f147990308aa2e36ab6e2266296771 Binary files /dev/null and b/release-notes/images/1_13/jsdocs.png differ diff --git a/release-notes/images/1_13/jsx-new-coloring.png b/release-notes/images/1_13/jsx-new-coloring.png new file mode 100644 index 0000000000000000000000000000000000000000..28b17ff6462095d245e3f1f02538716af6bdc9a9 --- /dev/null +++ b/release-notes/images/1_13/jsx-new-coloring.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a58f105a8ef9b265be4e4006c4fa7b46ffe4fd0b1a758a111982dccd663fc19c +size 167552 diff --git a/release-notes/images/1_13/letter-spacing.gif b/release-notes/images/1_13/letter-spacing.gif new file mode 100644 index 0000000000000000000000000000000000000000..11249b245ba63fc0e647a9a606f04394c70ba692 --- /dev/null +++ b/release-notes/images/1_13/letter-spacing.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7b9335e67c18b9789fd7a0a61ace4651f99052ab30087f9b66a4f1c2377ebeff +size 1273615 diff --git a/release-notes/images/1_13/markdown-heading-levels.png b/release-notes/images/1_13/markdown-heading-levels.png new file mode 100644 index 0000000000000000000000000000000000000000..f5c5eec5fa6bf9f1047a2f0f9fdd564d751b51c8 --- /dev/null +++ b/release-notes/images/1_13/markdown-heading-levels.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1cc2caeab7c61c7f1a87a37ad735831c38328e4e0554f9235dc3b44cc4649217 +size 124395 diff --git a/release-notes/images/1_13/merge-conflict.png b/release-notes/images/1_13/merge-conflict.png new file mode 100644 index 0000000000000000000000000000000000000000..82c68ab7d1380ead197aa1009125211117318963 Binary files /dev/null and b/release-notes/images/1_13/merge-conflict.png differ diff --git a/release-notes/images/1_13/new-setting-defaults.png b/release-notes/images/1_13/new-setting-defaults.png new file mode 100644 index 0000000000000000000000000000000000000000..6874b02a3a9956d97309a81093c7080ef2c5926c --- /dev/null +++ b/release-notes/images/1_13/new-setting-defaults.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a501d3f2ce32c2b82bbadd194c3ee3f3584bbc1199eaae5d684c4f7472d9a266 +size 237985 diff --git a/release-notes/images/1_13/release-highlights.png b/release-notes/images/1_13/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..a6a9059a3b81f084c3613e6cccb9743c929d5b6f Binary files /dev/null and b/release-notes/images/1_13/release-highlights.png differ diff --git a/release-notes/images/1_13/resize-find-widget.gif b/release-notes/images/1_13/resize-find-widget.gif new file mode 100644 index 0000000000000000000000000000000000000000..690c718ee69dad40d816402b40999ffbac135176 --- /dev/null +++ b/release-notes/images/1_13/resize-find-widget.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5872097c79771f058c2aa72f925394df144a1d98a16b9215140b6dc10417d935 +size 218230 diff --git a/release-notes/images/1_13/snippets-multi-cursor.gif b/release-notes/images/1_13/snippets-multi-cursor.gif new file mode 100644 index 0000000000000000000000000000000000000000..535e42a2c5e031a0a8601d89362a7e7a1e288010 --- /dev/null +++ b/release-notes/images/1_13/snippets-multi-cursor.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4b9f3b1daa450b0b35c94bd40508dd0989353098cc51063338dfc94b9a1e8028 +size 923600 diff --git a/release-notes/images/1_13/step-after.gif b/release-notes/images/1_13/step-after.gif new file mode 100644 index 0000000000000000000000000000000000000000..6d66cb2acec28a6d15d46982e4d4a7cb3b60e999 --- /dev/null +++ b/release-notes/images/1_13/step-after.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4862d19812e54a06bdd944c96db5add8d3eda8704b05369a9dac937aa1d747f1 +size 2265021 diff --git a/release-notes/images/1_13/step-before.gif b/release-notes/images/1_13/step-before.gif new file mode 100644 index 0000000000000000000000000000000000000000..d649d6c8836b2c89d7363d7772b8d0cdf9bc89cf --- /dev/null +++ b/release-notes/images/1_13/step-before.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cdc5e738124b088b1d457508add3b40cf9e3cc8581387c21e0477f9e8ea4b08e +size 1037229 diff --git a/release-notes/images/1_13/suggest.gif b/release-notes/images/1_13/suggest.gif new file mode 100644 index 0000000000000000000000000000000000000000..a310616e1af466c501b6c4b5854aa0495624feac --- /dev/null +++ b/release-notes/images/1_13/suggest.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:be565eeb78fb93d82bf50f566971242045e81136427b6257d0f1ec1191d579b6 +size 249532 diff --git a/release-notes/images/1_13/task-customize.gif b/release-notes/images/1_13/task-customize.gif new file mode 100644 index 0000000000000000000000000000000000000000..23317b7bc9fd3dbceb1af0cd430ef0c8b6eac4ba --- /dev/null +++ b/release-notes/images/1_13/task-customize.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d78bb0dc1a1da1ae8420562575bcd53a288f76be52688c5f1eca589268b4347a +size 325717 diff --git a/release-notes/images/1_13/task-selection.png b/release-notes/images/1_13/task-selection.png new file mode 100644 index 0000000000000000000000000000000000000000..c1d2148678c496149a257c5b7deb2d17e9e04ba0 Binary files /dev/null and b/release-notes/images/1_13/task-selection.png differ diff --git a/release-notes/images/1_13/terminal-vtop-after.png b/release-notes/images/1_13/terminal-vtop-after.png new file mode 100644 index 0000000000000000000000000000000000000000..5c335c53810a709374a02e0dcb8fe24545eca137 --- /dev/null +++ b/release-notes/images/1_13/terminal-vtop-after.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:581fe058365b78ec150efec23229788ed7a7b26443f13d53e00929ecf219dbd6 +size 106546 diff --git a/release-notes/images/1_13/terminal-vtop-before.png b/release-notes/images/1_13/terminal-vtop-before.png new file mode 100644 index 0000000000000000000000000000000000000000..370b6299fe6a8f30c9ccbf6dd92f93f199f18071 --- /dev/null +++ b/release-notes/images/1_13/terminal-vtop-before.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e047878d840797ecf34c73201c35c76c6864c42054f684f904d59aeb27f516de +size 113480 diff --git a/release-notes/images/1_13/typescript-workspace-symbol-names.png b/release-notes/images/1_13/typescript-workspace-symbol-names.png new file mode 100644 index 0000000000000000000000000000000000000000..046cb1e7c048d31dc5fd56b656eeaa9812370370 Binary files /dev/null and b/release-notes/images/1_13/typescript-workspace-symbol-names.png differ diff --git a/release-notes/images/1_13/uncover-matched-results.gif b/release-notes/images/1_13/uncover-matched-results.gif new file mode 100644 index 0000000000000000000000000000000000000000..caadd8208fccf256e0f18b8c018c88e29afcc396 --- /dev/null +++ b/release-notes/images/1_13/uncover-matched-results.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:27dcb3b9dc0b308bab639083bb66118de8039a4b98b6b09a52127e2ad7b953e7 +size 126341 diff --git a/release-notes/images/1_13/views.png b/release-notes/images/1_13/views.png new file mode 100644 index 0000000000000000000000000000000000000000..6f79600af1b24d2a402869722a57ce8cf1ff970a Binary files /dev/null and b/release-notes/images/1_13/views.png differ diff --git a/release-notes/images/1_14/add-root-folder.png b/release-notes/images/1_14/add-root-folder.png new file mode 100644 index 0000000000000000000000000000000000000000..1c96e54caae8e292495182b647ea0a916b03a92a Binary files /dev/null and b/release-notes/images/1_14/add-root-folder.png differ diff --git a/release-notes/images/1_14/auto-indent-on-move-lines.gif b/release-notes/images/1_14/auto-indent-on-move-lines.gif new file mode 100644 index 0000000000000000000000000000000000000000..d0f0e7732c36ee5fc081b441d91452f18224ca1b Binary files /dev/null and b/release-notes/images/1_14/auto-indent-on-move-lines.gif differ diff --git a/release-notes/images/1_14/auto-indent-on-paste.gif b/release-notes/images/1_14/auto-indent-on-paste.gif new file mode 100644 index 0000000000000000000000000000000000000000..421870401a723c6536b13b96c7820cb8e46c4561 Binary files /dev/null and b/release-notes/images/1_14/auto-indent-on-paste.gif differ diff --git a/release-notes/images/1_14/auto-indent-on-type.gif b/release-notes/images/1_14/auto-indent-on-type.gif new file mode 100644 index 0000000000000000000000000000000000000000..2a9dda395315eea04608c1d17d2397647d578c33 Binary files /dev/null and b/release-notes/images/1_14/auto-indent-on-type.gif differ diff --git a/release-notes/images/1_14/bot-labels-emmet.png b/release-notes/images/1_14/bot-labels-emmet.png new file mode 100644 index 0000000000000000000000000000000000000000..e00890a58e1c94dcffe43a08d96412c15bd034d3 Binary files /dev/null and b/release-notes/images/1_14/bot-labels-emmet.png differ diff --git a/release-notes/images/1_14/bot-labels-new-release.png b/release-notes/images/1_14/bot-labels-new-release.png new file mode 100644 index 0000000000000000000000000000000000000000..7caa9203cc65d6e30092bb89ed96ddf5c6be43e4 Binary files /dev/null and b/release-notes/images/1_14/bot-labels-new-release.png differ diff --git a/release-notes/images/1_14/close-unmodified.png b/release-notes/images/1_14/close-unmodified.png new file mode 100644 index 0000000000000000000000000000000000000000..52dc9e41741a782dcd7469f87fc4d1f3a441e40a Binary files /dev/null and b/release-notes/images/1_14/close-unmodified.png differ diff --git a/release-notes/images/1_14/commands-history.gif b/release-notes/images/1_14/commands-history.gif new file mode 100644 index 0000000000000000000000000000000000000000..13502faae5705c3225b6e1ba1fd2b36f290185e8 --- /dev/null +++ b/release-notes/images/1_14/commands-history.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f632b87bbbf76f68693f61b1ec63b7a9080313d2c8ee7e726c0c9539708ae4eb +size 332807 diff --git a/release-notes/images/1_14/diff-review-pane.png b/release-notes/images/1_14/diff-review-pane.png new file mode 100644 index 0000000000000000000000000000000000000000..6206dee8af4597ebbbfc077fba82d751906400af Binary files /dev/null and b/release-notes/images/1_14/diff-review-pane.png differ diff --git a/release-notes/images/1_14/emmet.gif b/release-notes/images/1_14/emmet.gif new file mode 100644 index 0000000000000000000000000000000000000000..3f35f0293c5a790992d87a739d58972f64290315 --- /dev/null +++ b/release-notes/images/1_14/emmet.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7e7e7dff8162193a30a8d23ea69de9602013f7113cadafcc111afe6d1e1ac10e +size 1020513 diff --git a/release-notes/images/1_14/empty-window-restore.gif b/release-notes/images/1_14/empty-window-restore.gif new file mode 100644 index 0000000000000000000000000000000000000000..65c1b0302776fe696d2697aec3adca9805e6d4da --- /dev/null +++ b/release-notes/images/1_14/empty-window-restore.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1b2f1c308988cb69230e34c83cfee7a33286d8a79c3c0aad0a7edc0d60998938 +size 185648 diff --git a/release-notes/images/1_14/explorer-context.png b/release-notes/images/1_14/explorer-context.png new file mode 100644 index 0000000000000000000000000000000000000000..a65e71c66f19f299c31310751d1b90e254d50e99 Binary files /dev/null and b/release-notes/images/1_14/explorer-context.png differ diff --git a/release-notes/images/1_14/extensions-view-sections.png b/release-notes/images/1_14/extensions-view-sections.png new file mode 100644 index 0000000000000000000000000000000000000000..822c4517a87764d0d649e82fe5979e6b75e95cbb Binary files /dev/null and b/release-notes/images/1_14/extensions-view-sections.png differ diff --git a/release-notes/images/1_14/github-issues-and-prs.gif b/release-notes/images/1_14/github-issues-and-prs.gif new file mode 100644 index 0000000000000000000000000000000000000000..db27b298761c62e64520b857403d0f845e286975 --- /dev/null +++ b/release-notes/images/1_14/github-issues-and-prs.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:05f2602be75d6d4b1074411bf19c14ac3a0c53c9419cd1ebb0a2878e4f957b18 +size 600383 diff --git a/release-notes/images/1_14/gitignore.gif b/release-notes/images/1_14/gitignore.gif new file mode 100644 index 0000000000000000000000000000000000000000..93cc9e6706bcb1d1b7cf95ac7f4d5bf198f18338 --- /dev/null +++ b/release-notes/images/1_14/gitignore.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e79e09a633dfeb09eaa5c9d3b408cc523aaf1f4e5bc7dd10f40221df0557e3b9 +size 2006445 diff --git a/release-notes/images/1_14/js-new-suggest.png b/release-notes/images/1_14/js-new-suggest.png new file mode 100644 index 0000000000000000000000000000000000000000..571d92a3c071cec39bc78de5b1b7417fea4575f7 Binary files /dev/null and b/release-notes/images/1_14/js-new-suggest.png differ diff --git a/release-notes/images/1_14/js-old-suggest.png b/release-notes/images/1_14/js-old-suggest.png new file mode 100644 index 0000000000000000000000000000000000000000..98eca1279d971fe9ed5ded3927364fc5430616ec Binary files /dev/null and b/release-notes/images/1_14/js-old-suggest.png differ diff --git a/release-notes/images/1_14/js-refactoring.gif b/release-notes/images/1_14/js-refactoring.gif new file mode 100644 index 0000000000000000000000000000000000000000..508f54ffd72cd82cd94781058c5998943362039d --- /dev/null +++ b/release-notes/images/1_14/js-refactoring.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e4ca5b6ed335dc081fe39616a005f8659c3c4072d73913b8bd347e9462da5dd5 +size 2184371 diff --git a/release-notes/images/1_14/js-super-suggestions.png b/release-notes/images/1_14/js-super-suggestions.png new file mode 100644 index 0000000000000000000000000000000000000000..9ec07f0a4c35b84e16fa5b5911161971ee9ecec5 Binary files /dev/null and b/release-notes/images/1_14/js-super-suggestions.png differ diff --git a/release-notes/images/1_14/md-breaks.png b/release-notes/images/1_14/md-breaks.png new file mode 100644 index 0000000000000000000000000000000000000000..dc87975d6c1bb43b1babf21e834f1c05367998e6 Binary files /dev/null and b/release-notes/images/1_14/md-breaks.png differ diff --git a/release-notes/images/1_14/md-no-breaks.png b/release-notes/images/1_14/md-no-breaks.png new file mode 100644 index 0000000000000000000000000000000000000000..d48c0b4456382c24e3194164dcddd9274f0e18f9 Binary files /dev/null and b/release-notes/images/1_14/md-no-breaks.png differ diff --git a/release-notes/images/1_14/minimap-horizontal-slider.gif b/release-notes/images/1_14/minimap-horizontal-slider.gif new file mode 100644 index 0000000000000000000000000000000000000000..05ca74498f698ee7ef6a34c0ddd306a3c36321e6 --- /dev/null +++ b/release-notes/images/1_14/minimap-horizontal-slider.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8f4b5ed6eb63c1130a6979c082f49864085b5dc077def7e60ef472efb79767d6 +size 3054701 diff --git a/release-notes/images/1_14/multi-root-quickopen.png b/release-notes/images/1_14/multi-root-quickopen.png new file mode 100644 index 0000000000000000000000000000000000000000..ef3ad0865efdd3275d618fc8d5b03dc03798106c Binary files /dev/null and b/release-notes/images/1_14/multi-root-quickopen.png differ diff --git a/release-notes/images/1_14/quick-switch-windows.gif b/release-notes/images/1_14/quick-switch-windows.gif new file mode 100644 index 0000000000000000000000000000000000000000..5d0d83e20de9be0b6a376ede82a15a42040755ca --- /dev/null +++ b/release-notes/images/1_14/quick-switch-windows.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a5208467246a1debe7a3a236760bd0d09b627925e2285629311ffb3b7ea8e4ea +size 279217 diff --git a/release-notes/images/1_14/release-highlights.png b/release-notes/images/1_14/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..2347fa674a3acf8de850f12b4f0b2e2ae9f3fe3c Binary files /dev/null and b/release-notes/images/1_14/release-highlights.png differ diff --git a/release-notes/images/1_14/search-multi-root.png b/release-notes/images/1_14/search-multi-root.png new file mode 100644 index 0000000000000000000000000000000000000000..3b68c2628c2dc198119537087d6aa3c92647d314 Binary files /dev/null and b/release-notes/images/1_14/search-multi-root.png differ diff --git a/release-notes/images/1_14/switch-window.png b/release-notes/images/1_14/switch-window.png new file mode 100644 index 0000000000000000000000000000000000000000..83a4fb23e9ab50bfdb8e204ee2cc497fb6e4b989 Binary files /dev/null and b/release-notes/images/1_14/switch-window.png differ diff --git a/release-notes/images/1_14/tasks-auto-detection.png b/release-notes/images/1_14/tasks-auto-detection.png new file mode 100644 index 0000000000000000000000000000000000000000..e0137255657f6b0712c64d0dc2fee3cb82b476d9 Binary files /dev/null and b/release-notes/images/1_14/tasks-auto-detection.png differ diff --git a/release-notes/images/1_14/tasks-global-menu.png b/release-notes/images/1_14/tasks-global-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..dee70260e9f87e0ae982f5bf37f4f2d16625432e Binary files /dev/null and b/release-notes/images/1_14/tasks-global-menu.png differ diff --git a/release-notes/images/1_14/tasks-matcher-attach.gif b/release-notes/images/1_14/tasks-matcher-attach.gif new file mode 100644 index 0000000000000000000000000000000000000000..4ee9ce05105177d88116e8aff40e79c938f036ad --- /dev/null +++ b/release-notes/images/1_14/tasks-matcher-attach.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:25b3ff5aa59b3d57b353c2cc4cb1a420c5ea5b971e1b431f8699902d22122abd +size 264583 diff --git a/release-notes/images/1_14/terminal-find.gif b/release-notes/images/1_14/terminal-find.gif new file mode 100644 index 0000000000000000000000000000000000000000..66fe1a6ab8b65382f6e214bb53f06af0a219ffed Binary files /dev/null and b/release-notes/images/1_14/terminal-find.gif differ diff --git a/release-notes/images/1_14/terminal-selection-select.gif b/release-notes/images/1_14/terminal-selection-select.gif new file mode 100644 index 0000000000000000000000000000000000000000..07d7b3ebf66143d7810826b05224952295939001 --- /dev/null +++ b/release-notes/images/1_14/terminal-selection-select.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ac7a9add5be2515451b64a802b32cb0dc55b50224855613e3a19d5faa98a94ad +size 533726 diff --git a/release-notes/images/1_14/terminal-selection-tmux.gif b/release-notes/images/1_14/terminal-selection-tmux.gif new file mode 100644 index 0000000000000000000000000000000000000000..2d1189496aee81e11a3130884c83c3a568c7748d Binary files /dev/null and b/release-notes/images/1_14/terminal-selection-tmux.gif differ diff --git a/release-notes/images/1_14/terminal-selection-word.gif b/release-notes/images/1_14/terminal-selection-word.gif new file mode 100644 index 0000000000000000000000000000000000000000..32acf6b64701d1d1d5dfc043d1cfd3f84b60d5f3 Binary files /dev/null and b/release-notes/images/1_14/terminal-selection-word.gif differ diff --git a/release-notes/images/1_14/ts-build-task.gif b/release-notes/images/1_14/ts-build-task.gif new file mode 100644 index 0000000000000000000000000000000000000000..ff89dba5f856cbc197f6f1bb6b0644278e54d0c8 --- /dev/null +++ b/release-notes/images/1_14/ts-build-task.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d51666b997d0d646dd2cec40f6be6a77c4160c6edab15b8aeb22f364a0a00af3 +size 4792727 diff --git a/release-notes/images/1_14/update.png b/release-notes/images/1_14/update.png new file mode 100644 index 0000000000000000000000000000000000000000..e6530ed931674a735e9eacb8357395eb76c61c69 Binary files /dev/null and b/release-notes/images/1_14/update.png differ diff --git a/release-notes/images/1_15/color-picker.png b/release-notes/images/1_15/color-picker.png new file mode 100644 index 0000000000000000000000000000000000000000..a4cca2b94d009cf0c65d94dbc48ee4c00303fdf2 Binary files /dev/null and b/release-notes/images/1_15/color-picker.png differ diff --git a/release-notes/images/1_15/compare-with-saved.png b/release-notes/images/1_15/compare-with-saved.png new file mode 100644 index 0000000000000000000000000000000000000000..eaa7a241dd4fb08a366aad2ceb90709229f5a767 Binary files /dev/null and b/release-notes/images/1_15/compare-with-saved.png differ diff --git a/release-notes/images/1_15/explorer-sorting.png b/release-notes/images/1_15/explorer-sorting.png new file mode 100644 index 0000000000000000000000000000000000000000..17377e1d6789ea674c5eb08e392839c1e583ab0b Binary files /dev/null and b/release-notes/images/1_15/explorer-sorting.png differ diff --git a/release-notes/images/1_15/folder_settings.png b/release-notes/images/1_15/folder_settings.png new file mode 100644 index 0000000000000000000000000000000000000000..8ef8e2b1b275f905651ace89ccf74074d64992eb --- /dev/null +++ b/release-notes/images/1_15/folder_settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b6ea5162463efcd2ee1cac1671e0eb2f7a9f1f8cd4e385faa11dd87e2c345e84 +size 155036 diff --git a/release-notes/images/1_15/loaded-scripts-explorer.gif b/release-notes/images/1_15/loaded-scripts-explorer.gif new file mode 100644 index 0000000000000000000000000000000000000000..f98d7e84bf04b721b3c7e675cc6a1d5024a2170e --- /dev/null +++ b/release-notes/images/1_15/loaded-scripts-explorer.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:defc292ba465192655bfb899d66754963334b9fa48deab1c995a65273edbbedf +size 5621068 diff --git a/release-notes/images/1_15/markdown-api-plugins.png b/release-notes/images/1_15/markdown-api-plugins.png new file mode 100644 index 0000000000000000000000000000000000000000..cdbbd27c9968a53100ba8b925d8fc97bdc232847 Binary files /dev/null and b/release-notes/images/1_15/markdown-api-plugins.png differ diff --git a/release-notes/images/1_15/markdown-api-scripts.png b/release-notes/images/1_15/markdown-api-scripts.png new file mode 100644 index 0000000000000000000000000000000000000000..32b8180974ffcf5138b404efe863c1ea438fec8b Binary files /dev/null and b/release-notes/images/1_15/markdown-api-scripts.png differ diff --git a/release-notes/images/1_15/markdown-api-styles.png b/release-notes/images/1_15/markdown-api-styles.png new file mode 100644 index 0000000000000000000000000000000000000000..1bb553317ec69d26484ac5551be30980e465e42a Binary files /dev/null and b/release-notes/images/1_15/markdown-api-styles.png differ diff --git a/release-notes/images/1_15/markdown-preview-search.png b/release-notes/images/1_15/markdown-preview-search.png new file mode 100644 index 0000000000000000000000000000000000000000..191bbf74998bd121d7dd1c1a9cbf65b914b0e5a5 --- /dev/null +++ b/release-notes/images/1_15/markdown-preview-search.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f1a10aeee803c6e3d24b640ce0220140279810a65346984cc03638c34b309412 +size 229119 diff --git a/release-notes/images/1_15/markdown-security.gif b/release-notes/images/1_15/markdown-security.gif new file mode 100644 index 0000000000000000000000000000000000000000..a297b4a5868813a00239980a6b211c79a1791b24 --- /dev/null +++ b/release-notes/images/1_15/markdown-security.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e2f93a9a421c7d348f6a5ba204a2f8f293ea1efd4825c71392d90845fb178b90 +size 2863136 diff --git a/release-notes/images/1_15/mr_debug.png b/release-notes/images/1_15/mr_debug.png new file mode 100644 index 0000000000000000000000000000000000000000..1df173bec3457e7cb9b20ede5927b4bb94221620 Binary files /dev/null and b/release-notes/images/1_15/mr_debug.png differ diff --git a/release-notes/images/1_15/multiroot-search-results.png b/release-notes/images/1_15/multiroot-search-results.png new file mode 100644 index 0000000000000000000000000000000000000000..3fbee9a7c2fb79309e4ad6fde206bb4b64fe4568 Binary files /dev/null and b/release-notes/images/1_15/multiroot-search-results.png differ diff --git a/release-notes/images/1_15/open_workspace.png b/release-notes/images/1_15/open_workspace.png new file mode 100644 index 0000000000000000000000000000000000000000..346efb9c4183bf4f529dcb03c1cd68ca87f97b5e Binary files /dev/null and b/release-notes/images/1_15/open_workspace.png differ diff --git a/release-notes/images/1_15/proxy-authentication.png b/release-notes/images/1_15/proxy-authentication.png new file mode 100644 index 0000000000000000000000000000000000000000..c10d4cf5a458f568d757434c46c6ee39423c6c37 Binary files /dev/null and b/release-notes/images/1_15/proxy-authentication.png differ diff --git a/release-notes/images/1_15/react-tutorial.png b/release-notes/images/1_15/react-tutorial.png new file mode 100644 index 0000000000000000000000000000000000000000..871c5348929772614ea7a13639590deba3376c4d --- /dev/null +++ b/release-notes/images/1_15/react-tutorial.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:74a600f1254d5ea9d4e41f7ed31af50327f149b8f991cfddf0bd6885a6698e66 +size 123952 diff --git a/release-notes/images/1_15/recent_workspace.png b/release-notes/images/1_15/recent_workspace.png new file mode 100644 index 0000000000000000000000000000000000000000..449a0a317594bbcbda6c244a096a4a9a293a7ca9 Binary files /dev/null and b/release-notes/images/1_15/recent_workspace.png differ diff --git a/release-notes/images/1_15/release-highlights.png b/release-notes/images/1_15/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..e5a4395b7f76a26c88b73435533f6c01fc586e5f Binary files /dev/null and b/release-notes/images/1_15/release-highlights.png differ diff --git a/release-notes/images/1_15/remove_history.gif b/release-notes/images/1_15/remove_history.gif new file mode 100644 index 0000000000000000000000000000000000000000..2bbc8d916c6f852e41832405495290b2eb0e300a Binary files /dev/null and b/release-notes/images/1_15/remove_history.gif differ diff --git a/release-notes/images/1_15/root_icon.png b/release-notes/images/1_15/root_icon.png new file mode 100644 index 0000000000000000000000000000000000000000..67eff8448e5e4161e2583c3396727e6fb4265e00 Binary files /dev/null and b/release-notes/images/1_15/root_icon.png differ diff --git a/release-notes/images/1_15/save_workspace.png b/release-notes/images/1_15/save_workspace.png new file mode 100644 index 0000000000000000000000000000000000000000..ec9bb2036e307fdb3293f58f5bf52611545f17b5 Binary files /dev/null and b/release-notes/images/1_15/save_workspace.png differ diff --git a/release-notes/images/1_15/search-options.png b/release-notes/images/1_15/search-options.png new file mode 100644 index 0000000000000000000000000000000000000000..fba4e08db12befa66a1158dd0660367764a812cc Binary files /dev/null and b/release-notes/images/1_15/search-options.png differ diff --git a/release-notes/images/1_15/settings_dropdown.png b/release-notes/images/1_15/settings_dropdown.png new file mode 100644 index 0000000000000000000000000000000000000000..7663823ce8f32cdbade041b0de48499157e2b015 Binary files /dev/null and b/release-notes/images/1_15/settings_dropdown.png differ diff --git a/release-notes/images/1_15/snippet-choice.gif b/release-notes/images/1_15/snippet-choice.gif new file mode 100644 index 0000000000000000000000000000000000000000..55869c2c50571927e6f13ac7aa7fbeba83d32d12 --- /dev/null +++ b/release-notes/images/1_15/snippet-choice.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0d09f2bc99113cb7e10f2fc33d3b332a00e670a472937cc48a9efff391d8fa02 +size 182865 diff --git a/release-notes/images/1_15/tasks-status-bar.png b/release-notes/images/1_15/tasks-status-bar.png new file mode 100644 index 0000000000000000000000000000000000000000..788f3495a7c9a2b5ff1e0d28a345b095dd659da0 Binary files /dev/null and b/release-notes/images/1_15/tasks-status-bar.png differ diff --git a/release-notes/images/1_15/terminal_quickpick.png b/release-notes/images/1_15/terminal_quickpick.png new file mode 100644 index 0000000000000000000000000000000000000000..6c3e24aa283ea89338f26da477e6ab235dc846b1 Binary files /dev/null and b/release-notes/images/1_15/terminal_quickpick.png differ diff --git a/release-notes/images/1_15/token_color_customization.png b/release-notes/images/1_15/token_color_customization.png new file mode 100644 index 0000000000000000000000000000000000000000..ae2a89847a94aea9969babe75ec4d2d160f4d91a Binary files /dev/null and b/release-notes/images/1_15/token_color_customization.png differ diff --git a/release-notes/images/1_15/token_color_customization_advanced.png b/release-notes/images/1_15/token_color_customization_advanced.png new file mode 100644 index 0000000000000000000000000000000000000000..d441c80bd58f9c89b319aa9ed973378be82c4365 Binary files /dev/null and b/release-notes/images/1_15/token_color_customization_advanced.png differ diff --git a/release-notes/images/1_15/unsupported_setting_info.png b/release-notes/images/1_15/unsupported_setting_info.png new file mode 100644 index 0000000000000000000000000000000000000000..3becd2c80fa62821d714de41168e87699e4bad5e Binary files /dev/null and b/release-notes/images/1_15/unsupported_setting_info.png differ diff --git a/release-notes/images/1_15/views_management.gif b/release-notes/images/1_15/views_management.gif new file mode 100644 index 0000000000000000000000000000000000000000..26f19f6482b3421bb192a61bc2f6f5dfe6bc35fa --- /dev/null +++ b/release-notes/images/1_15/views_management.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3dbbf467f59881d48547e3a5dcefbee49e5048a40d30804529da421c3cc24524 +size 2295510 diff --git a/release-notes/images/1_15/workspace.gif b/release-notes/images/1_15/workspace.gif new file mode 100644 index 0000000000000000000000000000000000000000..f373d76e124a375651ad71c696d48436080547f7 --- /dev/null +++ b/release-notes/images/1_15/workspace.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:21fbdf37f47d9add23383856d4bcf38a6c9a2ce6daba5024d13f79b6dc004b73 +size 353950 diff --git a/release-notes/images/1_15/workspace.png b/release-notes/images/1_15/workspace.png new file mode 100644 index 0000000000000000000000000000000000000000..78eb59136ac6520437d3372f270effe824ce4c83 Binary files /dev/null and b/release-notes/images/1_15/workspace.png differ diff --git a/release-notes/images/1_15/workspace_settings.png b/release-notes/images/1_15/workspace_settings.png new file mode 100644 index 0000000000000000000000000000000000000000..f44e36c82dabbc80ad5360155d02f8578a341b45 --- /dev/null +++ b/release-notes/images/1_15/workspace_settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ef28aa1be78aed3c739f809b4010cc2c655f3cf7996f92291e56648168778774 +size 194369 diff --git a/release-notes/images/1_16/auto-close1.gif b/release-notes/images/1_16/auto-close1.gif new file mode 100644 index 0000000000000000000000000000000000000000..ff4bd6a625ffe90dc79b5014a767dc088450cb8a --- /dev/null +++ b/release-notes/images/1_16/auto-close1.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fdc932fcf089230387f4ea7ddaf5ebdf044293e49f3a40532fea00ca3ea76249 +size 101197 diff --git a/release-notes/images/1_16/auto-close2.gif b/release-notes/images/1_16/auto-close2.gif new file mode 100644 index 0000000000000000000000000000000000000000..52bd6d692b4cf7f960c0c0d01799c2f4270464f7 Binary files /dev/null and b/release-notes/images/1_16/auto-close2.gif differ diff --git a/release-notes/images/1_16/color-picker-html.png b/release-notes/images/1_16/color-picker-html.png new file mode 100644 index 0000000000000000000000000000000000000000..f4ed9f2c300a1e62962666c13e303023504ce2fe Binary files /dev/null and b/release-notes/images/1_16/color-picker-html.png differ diff --git a/release-notes/images/1_16/eh-breakpoints.gif b/release-notes/images/1_16/eh-breakpoints.gif new file mode 100644 index 0000000000000000000000000000000000000000..32621b79fffd27287bf0ccb2a2403a5166b49a35 --- /dev/null +++ b/release-notes/images/1_16/eh-breakpoints.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:93353b594753a5e465dd490c30c99c07bbe0a05d6d55152cab2b71e01c5f9c4f +size 2753410 diff --git a/release-notes/images/1_16/exthost-restart.gif b/release-notes/images/1_16/exthost-restart.gif new file mode 100644 index 0000000000000000000000000000000000000000..975ed8f021a1505adf4e023a4d36ad0923afb34e --- /dev/null +++ b/release-notes/images/1_16/exthost-restart.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2cb8c0a3981d7ca3a609ed8c28a63be087b4e28ba8a0eec099e8ac75eb8916c2 +size 1842480 diff --git a/release-notes/images/1_16/folder-drop.gif b/release-notes/images/1_16/folder-drop.gif new file mode 100644 index 0000000000000000000000000000000000000000..9dada2c7c485d2448160299e93cfc76b086b39e7 --- /dev/null +++ b/release-notes/images/1_16/folder-drop.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8cce481281c7742d60f8aedaa112ee2a773d3164bbfd608d83679783fee85225 +size 391149 diff --git a/release-notes/images/1_16/markdown-refresh.png b/release-notes/images/1_16/markdown-refresh.png new file mode 100644 index 0000000000000000000000000000000000000000..72905531b2f6088f0172d9078e87a209cde81b9e Binary files /dev/null and b/release-notes/images/1_16/markdown-refresh.png differ diff --git a/release-notes/images/1_16/multi-root-dnd.gif b/release-notes/images/1_16/multi-root-dnd.gif new file mode 100644 index 0000000000000000000000000000000000000000..7a915395b4da5f44560c824ef0b96a91c1af4c7d --- /dev/null +++ b/release-notes/images/1_16/multi-root-dnd.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:37dae6474fd9bdf0eb6f38046f1c7176153f74e39b24f83b4eb9b2f1e73a08db +size 385438 diff --git a/release-notes/images/1_16/multi-root-transition.gif b/release-notes/images/1_16/multi-root-transition.gif new file mode 100644 index 0000000000000000000000000000000000000000..2006d181014a3a51be0688c6134cd9edee27b927 --- /dev/null +++ b/release-notes/images/1_16/multi-root-transition.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:06e111508904330cd3c79688360defdd2182d02106a7faf0887b463df8cba61c +size 412252 diff --git a/release-notes/images/1_16/release-highlights.png b/release-notes/images/1_16/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..6b0428346417438ef7c3ee5323954c9d873ff93c Binary files /dev/null and b/release-notes/images/1_16/release-highlights.png differ diff --git a/release-notes/images/1_16/scm-multiroot.png b/release-notes/images/1_16/scm-multiroot.png new file mode 100644 index 0000000000000000000000000000000000000000..1dcc297cde4a5803076d03f626679cf4f45640e7 --- /dev/null +++ b/release-notes/images/1_16/scm-multiroot.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:afb7e0609d023fd23e19a0533a0741e82e7ff7b70f0b0f2600dd95a0c76d80fb +size 162513 diff --git a/release-notes/images/1_16/search-dnd.gif b/release-notes/images/1_16/search-dnd.gif new file mode 100644 index 0000000000000000000000000000000000000000..cf4191e733dc36bb780d5fa5ca5d3cb3daaa78bf --- /dev/null +++ b/release-notes/images/1_16/search-dnd.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:54e7351e3ea9446075a82685f89f845b6ca98f493c5eeb164cbdfadb4d7aec67 +size 690956 diff --git a/release-notes/images/1_16/smooth-scrolling.gif b/release-notes/images/1_16/smooth-scrolling.gif new file mode 100644 index 0000000000000000000000000000000000000000..1713fb1b72d4fe9d11a7626fe2c578256b661a65 --- /dev/null +++ b/release-notes/images/1_16/smooth-scrolling.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b6c3bcda232e3cacc147ca19ab63224a8072511f5283c196eb8561522c9861f5 +size 7483540 diff --git a/release-notes/images/1_16/terminal-find.gif b/release-notes/images/1_16/terminal-find.gif new file mode 100644 index 0000000000000000000000000000000000000000..06173f49f7cc6f03be58db680a527a6f35fbe8e9 Binary files /dev/null and b/release-notes/images/1_16/terminal-find.gif differ diff --git a/release-notes/images/1_16/terminal-quick-pick.png b/release-notes/images/1_16/terminal-quick-pick.png new file mode 100644 index 0000000000000000000000000000000000000000..f9fefce97fd775b518e7290d7a9b25c830f8990d Binary files /dev/null and b/release-notes/images/1_16/terminal-quick-pick.png differ diff --git a/release-notes/images/1_16/ts-extract.gif b/release-notes/images/1_16/ts-extract.gif new file mode 100644 index 0000000000000000000000000000000000000000..ded33c000f4b2fefe6ed453af8a7e9f12a8359ba --- /dev/null +++ b/release-notes/images/1_16/ts-extract.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:95ee437335c0e9ab0770dfaa3e66cef910c0ef3436e5eed792999b73fb895c06 +size 6387207 diff --git a/release-notes/images/1_17/console_messages.gif b/release-notes/images/1_17/console_messages.gif new file mode 100644 index 0000000000000000000000000000000000000000..301504212679fb44bcf0982a9d8166e40dd4b92d --- /dev/null +++ b/release-notes/images/1_17/console_messages.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b5fdcdbe3d8eefd3e880c102373460f396d8faf5b2482d9dc9c91a8ac4b4431b +size 385761 diff --git a/release-notes/images/1_17/extension_recommendations.png b/release-notes/images/1_17/extension_recommendations.png new file mode 100644 index 0000000000000000000000000000000000000000..b75021539bfd624d8ba9d27f7849a105068aa287 Binary files /dev/null and b/release-notes/images/1_17/extension_recommendations.png differ diff --git a/release-notes/images/1_17/git-stash.png b/release-notes/images/1_17/git-stash.png new file mode 100644 index 0000000000000000000000000000000000000000..0cc7073c459d2850fb77236297950bb066f138fb Binary files /dev/null and b/release-notes/images/1_17/git-stash.png differ diff --git a/release-notes/images/1_17/js-markdown-intellisense.png b/release-notes/images/1_17/js-markdown-intellisense.png new file mode 100644 index 0000000000000000000000000000000000000000..a7a4818f81207d97d0536fb2d5182ea8794fbf20 --- /dev/null +++ b/release-notes/images/1_17/js-markdown-intellisense.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9e69deeba723e79c15d9c218a082f5f73a57f1f53cee0edd3d8c9b62f6083348 +size 111760 diff --git a/release-notes/images/1_17/labelformat.png b/release-notes/images/1_17/labelformat.png new file mode 100644 index 0000000000000000000000000000000000000000..d2b74f967c7784fa8ab5f0a691f70afcc465967d Binary files /dev/null and b/release-notes/images/1_17/labelformat.png differ diff --git a/release-notes/images/1_17/mac-insiders-green.png b/release-notes/images/1_17/mac-insiders-green.png new file mode 100644 index 0000000000000000000000000000000000000000..772ad0e1d8da859fbfc8ef1567cf2be7a6d00196 Binary files /dev/null and b/release-notes/images/1_17/mac-insiders-green.png differ diff --git a/release-notes/images/1_17/mac-stable-orange.png b/release-notes/images/1_17/mac-stable-orange.png new file mode 100644 index 0000000000000000000000000000000000000000..2f76c2f4f4508cab848b242d57a0a2d09ba26399 Binary files /dev/null and b/release-notes/images/1_17/mac-stable-orange.png differ diff --git a/release-notes/images/1_17/markdown-fenced-commenting.gif b/release-notes/images/1_17/markdown-fenced-commenting.gif new file mode 100644 index 0000000000000000000000000000000000000000..5368d9738923d10226c7821bb53942c43b4b3f0a --- /dev/null +++ b/release-notes/images/1_17/markdown-fenced-commenting.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c4279fc777b6b3ec8d07e9e3f95e055c630cb501198391d358795ce64d7dc688 +size 1039919 diff --git a/release-notes/images/1_17/nativetabs.png b/release-notes/images/1_17/nativetabs.png new file mode 100644 index 0000000000000000000000000000000000000000..9d18c7918ece2194ebae2e38273a6080c17ee014 Binary files /dev/null and b/release-notes/images/1_17/nativetabs.png differ diff --git a/release-notes/images/1_17/offside-folding.gif b/release-notes/images/1_17/offside-folding.gif new file mode 100644 index 0000000000000000000000000000000000000000..81f117be4b889f0b4ecb3b73efcbfaeb31a31965 --- /dev/null +++ b/release-notes/images/1_17/offside-folding.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ee8d21909e692d7a862bbbba9e038fc2ab03bfba2884c0f0e8a3219d53868c8a +size 402073 diff --git a/release-notes/images/1_17/picker.png b/release-notes/images/1_17/picker.png new file mode 100644 index 0000000000000000000000000000000000000000..d9a3e00bd4a1559497fa3e2b75f6ba2c8fce39db Binary files /dev/null and b/release-notes/images/1_17/picker.png differ diff --git a/release-notes/images/1_17/python-string-sub-colorization.png b/release-notes/images/1_17/python-string-sub-colorization.png new file mode 100644 index 0000000000000000000000000000000000000000..10e17b63441f5090b54a1c16e8f2eb386ca6cb47 Binary files /dev/null and b/release-notes/images/1_17/python-string-sub-colorization.png differ diff --git a/release-notes/images/1_17/quick-suggestion-path-intellisense.gif b/release-notes/images/1_17/quick-suggestion-path-intellisense.gif new file mode 100644 index 0000000000000000000000000000000000000000..9e8d0ceae3dfeed858074ab3121276fab2a1d71b --- /dev/null +++ b/release-notes/images/1_17/quick-suggestion-path-intellisense.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:05c3f9a65103893584b96dbf1591bde36ca5e527f4c8cf8d62839b7159752aa3 +size 3161194 diff --git a/release-notes/images/1_17/regexp-colorization-improvements.png b/release-notes/images/1_17/regexp-colorization-improvements.png new file mode 100644 index 0000000000000000000000000000000000000000..0fb8fcf27de4533d7bf7629e21261029a13118cb Binary files /dev/null and b/release-notes/images/1_17/regexp-colorization-improvements.png differ diff --git a/release-notes/images/1_17/region-folding.gif b/release-notes/images/1_17/region-folding.gif new file mode 100644 index 0000000000000000000000000000000000000000..9470b850dc69795a6018489ea7d80ba51287be90 --- /dev/null +++ b/release-notes/images/1_17/region-folding.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f7c0dcc31e7218d5097c6abc3ab9424d481eda3fd6f3a9e41f7edf2407608d3d +size 967287 diff --git a/release-notes/images/1_17/release-highlights.png b/release-notes/images/1_17/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..e08906b0b1477a723e7daa80190f2ba23bc3b277 Binary files /dev/null and b/release-notes/images/1_17/release-highlights.png differ diff --git a/release-notes/images/1_17/remote_fs.png b/release-notes/images/1_17/remote_fs.png new file mode 100644 index 0000000000000000000000000000000000000000..b4d60d4457757813a201b2f253d942877c8dc530 Binary files /dev/null and b/release-notes/images/1_17/remote_fs.png differ diff --git a/release-notes/images/1_17/ruby-interpolation-colorization.png b/release-notes/images/1_17/ruby-interpolation-colorization.png new file mode 100644 index 0000000000000000000000000000000000000000..bb19860785b8a978d8b61fca14b9f7da745f16af Binary files /dev/null and b/release-notes/images/1_17/ruby-interpolation-colorization.png differ diff --git a/release-notes/images/1_17/scm.png b/release-notes/images/1_17/scm.png new file mode 100644 index 0000000000000000000000000000000000000000..aceb33f90fecbec55179a6400903f77b57592048 --- /dev/null +++ b/release-notes/images/1_17/scm.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:975a66a07476b28e3587260d3cc27a03e18533224ec6cb04fc1535e3ed35e87a +size 118815 diff --git a/release-notes/images/1_17/snippet_buckets.png b/release-notes/images/1_17/snippet_buckets.png new file mode 100644 index 0000000000000000000000000000000000000000..b8cb5c18f747347537e6b30f9c7c23dc43ac59fc Binary files /dev/null and b/release-notes/images/1_17/snippet_buckets.png differ diff --git a/release-notes/images/1_17/tasks-multi-root.png b/release-notes/images/1_17/tasks-multi-root.png new file mode 100644 index 0000000000000000000000000000000000000000..13283b7c19ed9d7d411b9f210fcef0b62db7ec66 Binary files /dev/null and b/release-notes/images/1_17/tasks-multi-root.png differ diff --git a/release-notes/images/1_17/terminal_60fps.gif b/release-notes/images/1_17/terminal_60fps.gif new file mode 100644 index 0000000000000000000000000000000000000000..82ee7972859c004cd07f7cf23395d9b57b915e61 --- /dev/null +++ b/release-notes/images/1_17/terminal_60fps.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:10c2e6c18d6a3a4e08c93b38d9673142329379246c401b73405ec58558988f9c +size 3787695 diff --git a/release-notes/images/1_17/touchbar.gif b/release-notes/images/1_17/touchbar.gif new file mode 100644 index 0000000000000000000000000000000000000000..f923c60661a0a892a477d0fe1b81e2d07c7adce6 --- /dev/null +++ b/release-notes/images/1_17/touchbar.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5122fbf3d4490552fa5b2bfe83ae26a6065d415d2c456c6603d0b035e1c8300c +size 205581 diff --git a/release-notes/images/1_17/tsc-build-and-watch.png b/release-notes/images/1_17/tsc-build-and-watch.png new file mode 100644 index 0000000000000000000000000000000000000000..7d225d3a2badc913442d96f91fbafa7431980906 Binary files /dev/null and b/release-notes/images/1_17/tsc-build-and-watch.png differ diff --git a/release-notes/images/1_17/wait.gif b/release-notes/images/1_17/wait.gif new file mode 100644 index 0000000000000000000000000000000000000000..eab00f7f71c7e4d728b1ec84dbb5bc8f01063e87 --- /dev/null +++ b/release-notes/images/1_17/wait.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f898840b1a88022dd119884b4b299c960aa6ce508322025adbb5f45e7c40517d +size 189502 diff --git a/release-notes/images/1_17/warning-color.png b/release-notes/images/1_17/warning-color.png new file mode 100644 index 0000000000000000000000000000000000000000..b52e96f2b20b6300d9716b94f493566dd37d2243 Binary files /dev/null and b/release-notes/images/1_17/warning-color.png differ diff --git a/release-notes/images/1_17/windows-insiders-green.png b/release-notes/images/1_17/windows-insiders-green.png new file mode 100644 index 0000000000000000000000000000000000000000..9b387d89532e45adab7feb6e64583aa102cec5bb Binary files /dev/null and b/release-notes/images/1_17/windows-insiders-green.png differ diff --git a/release-notes/images/1_17/windows-stable-orange.png b/release-notes/images/1_17/windows-stable-orange.png new file mode 100644 index 0000000000000000000000000000000000000000..7d9cbcbcaadc1c6dcac52005c18c777cc5ad8029 Binary files /dev/null and b/release-notes/images/1_17/windows-stable-orange.png differ diff --git a/release-notes/images/1_18/blueicon.png b/release-notes/images/1_18/blueicon.png new file mode 100644 index 0000000000000000000000000000000000000000..f8d6c866000fd6b5d5ecec2b95b135557484a9df Binary files /dev/null and b/release-notes/images/1_18/blueicon.png differ diff --git a/release-notes/images/1_18/debug-status.png b/release-notes/images/1_18/debug-status.png new file mode 100644 index 0000000000000000000000000000000000000000..5e638a52f7e2b1f750b25bb4a6778ce9abcfd492 Binary files /dev/null and b/release-notes/images/1_18/debug-status.png differ diff --git a/release-notes/images/1_18/diff.gif b/release-notes/images/1_18/diff.gif new file mode 100644 index 0000000000000000000000000000000000000000..7b8c4ef929f99dc842ca34202e93a98a5d544034 --- /dev/null +++ b/release-notes/images/1_18/diff.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3c9e5e436b4f700ad5032cf1ac425beaf851acbba9cdb70f09f513acdb328f30 +size 4162951 diff --git a/release-notes/images/1_18/difftitle.png b/release-notes/images/1_18/difftitle.png new file mode 100644 index 0000000000000000000000000000000000000000..3f61eb59f6d44851f0ba23be1215ceb851b11d65 Binary files /dev/null and b/release-notes/images/1_18/difftitle.png differ diff --git a/release-notes/images/1_18/editor-decorations.png b/release-notes/images/1_18/editor-decorations.png new file mode 100644 index 0000000000000000000000000000000000000000..96ee8e55fe9520fd0bd9857fad891936c212d33e Binary files /dev/null and b/release-notes/images/1_18/editor-decorations.png differ diff --git a/release-notes/images/1_18/git-decorations.png b/release-notes/images/1_18/git-decorations.png new file mode 100644 index 0000000000000000000000000000000000000000..0ef7d436d1f70e39243f749841be2e9ac1f42b32 --- /dev/null +++ b/release-notes/images/1_18/git-decorations.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d2c4fe90d31e126b8fbced6c0ad54e0f7e1e98576a0dd140856cc798a05c090c +size 138719 diff --git a/release-notes/images/1_18/merge.png b/release-notes/images/1_18/merge.png new file mode 100644 index 0000000000000000000000000000000000000000..d883a2625a8bf193627eec43e2b5f7e0e532d689 --- /dev/null +++ b/release-notes/images/1_18/merge.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:edd78a2bb573b23c445c66ffb965f00552e53b8dd2ff580de29303e91f888030 +size 136018 diff --git a/release-notes/images/1_18/move-confirmation.png b/release-notes/images/1_18/move-confirmation.png new file mode 100644 index 0000000000000000000000000000000000000000..d7412d0128745c306f7c4c7bbcdbdaa2ca40bc6d Binary files /dev/null and b/release-notes/images/1_18/move-confirmation.png differ diff --git a/release-notes/images/1_18/multiroot.gif b/release-notes/images/1_18/multiroot.gif new file mode 100644 index 0000000000000000000000000000000000000000..457f583331f393db3d2a663733b9caf1eb2fe660 --- /dev/null +++ b/release-notes/images/1_18/multiroot.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5daf116c34aac5405a04f9545e134119f9ba4526283bd8a87bb1f15dd88fc905 +size 2730138 diff --git a/release-notes/images/1_18/panel-title.gif b/release-notes/images/1_18/panel-title.gif new file mode 100644 index 0000000000000000000000000000000000000000..0ae4b3169d7f55591965e24cfa8e9d1021a66dd6 --- /dev/null +++ b/release-notes/images/1_18/panel-title.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d8b0d93af518d5e2842907c4a38ea99f68220b7f5cf16df6bcb0aa4a618f4f6a +size 234519 diff --git a/release-notes/images/1_18/recommendationinstall-configure.gif b/release-notes/images/1_18/recommendationinstall-configure.gif new file mode 100644 index 0000000000000000000000000000000000000000..f1597ab595d784a772b550ee15af78df7c9afdc5 --- /dev/null +++ b/release-notes/images/1_18/recommendationinstall-configure.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:18d82f8e5a6280af183bdd5ebabb06a44d4a3f274c7e5694d4e3f0ebc45019a1 +size 351982 diff --git a/release-notes/images/1_18/recommendations-badge.gif b/release-notes/images/1_18/recommendations-badge.gif new file mode 100644 index 0000000000000000000000000000000000000000..4d8cb87e9de07a2c3f6c25d595f49a550f48348d --- /dev/null +++ b/release-notes/images/1_18/recommendations-badge.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:36e5081286d116b9bb6ecaf59210163effc69b383a925b775a67692f7b5e86f5 +size 1607111 diff --git a/release-notes/images/1_18/release-highlights.png b/release-notes/images/1_18/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..213c8f34d02a9de13f3de05b250b08f66005c977 Binary files /dev/null and b/release-notes/images/1_18/release-highlights.png differ diff --git a/release-notes/images/1_18/repl-color.png b/release-notes/images/1_18/repl-color.png new file mode 100644 index 0000000000000000000000000000000000000000..4b020161e03beab85dfe8fbc46c2beeb33123439 Binary files /dev/null and b/release-notes/images/1_18/repl-color.png differ diff --git a/release-notes/images/1_18/string-quick-suggestions.gif b/release-notes/images/1_18/string-quick-suggestions.gif new file mode 100644 index 0000000000000000000000000000000000000000..2596559cb568e537ef2e10d6c4b80e9a28a88be2 --- /dev/null +++ b/release-notes/images/1_18/string-quick-suggestions.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8a06690b980377d1240e831b2e5a112fdadebf9b3a97be9c99bce9dd717865bf +size 515965 diff --git a/release-notes/images/1_18/terminal-faint-text.png b/release-notes/images/1_18/terminal-faint-text.png new file mode 100644 index 0000000000000000000000000000000000000000..196d6b163deaf1cf43ca7c37651870fa738c00b3 Binary files /dev/null and b/release-notes/images/1_18/terminal-faint-text.png differ diff --git a/release-notes/images/1_18/ts-auto-import-post.png b/release-notes/images/1_18/ts-auto-import-post.png new file mode 100644 index 0000000000000000000000000000000000000000..23687238f56f4c12aaac7b57f47e10c76bf261b6 Binary files /dev/null and b/release-notes/images/1_18/ts-auto-import-post.png differ diff --git a/release-notes/images/1_18/ts-auto-import-pre.png b/release-notes/images/1_18/ts-auto-import-pre.png new file mode 100644 index 0000000000000000000000000000000000000000..2e0e879848e662672a6193a1af0841408347fd2d Binary files /dev/null and b/release-notes/images/1_18/ts-auto-import-pre.png differ diff --git a/release-notes/images/1_18/ts-extract-local.gif b/release-notes/images/1_18/ts-extract-local.gif new file mode 100644 index 0000000000000000000000000000000000000000..bcf27710e0c6bf09c702a846f129b7c6e58bd44e --- /dev/null +++ b/release-notes/images/1_18/ts-extract-local.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:39bed5a6de19d5ee35faeeb1e10377081d58a5deeda73e777d44d712a377b02e +size 5463780 diff --git a/release-notes/images/1_18/ts-localizable-errors.png b/release-notes/images/1_18/ts-localizable-errors.png new file mode 100644 index 0000000000000000000000000000000000000000..d3a515c1c5f4066c73a8ec0c3a1f98bc37f43dc8 Binary files /dev/null and b/release-notes/images/1_18/ts-localizable-errors.png differ diff --git a/release-notes/images/1_18/ts-npm-install-quick-fix.png b/release-notes/images/1_18/ts-npm-install-quick-fix.png new file mode 100644 index 0000000000000000000000000000000000000000..c19201b1c8ba080adc365f6f61f7cdb8a5a64424 Binary files /dev/null and b/release-notes/images/1_18/ts-npm-install-quick-fix.png differ diff --git a/release-notes/images/1_18/twistieless-fileicons.png b/release-notes/images/1_18/twistieless-fileicons.png new file mode 100644 index 0000000000000000000000000000000000000000..af42805c536bb442c35f7027b79405fe2334112e Binary files /dev/null and b/release-notes/images/1_18/twistieless-fileicons.png differ diff --git a/release-notes/images/1_18/vertical-panel.png b/release-notes/images/1_18/vertical-panel.png new file mode 100644 index 0000000000000000000000000000000000000000..7f89c144f492bfefcae0afb9fb30d36cf56ee5a8 --- /dev/null +++ b/release-notes/images/1_18/vertical-panel.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6d352d78bf837035369171975401eb4f1e697f6cd72caf26cd4d3853972e1cb1 +size 254379 diff --git a/release-notes/images/1_19/character-entities.png b/release-notes/images/1_19/character-entities.png new file mode 100644 index 0000000000000000000000000000000000000000..f822d709e7e977b27e90ed0d26ebe036ddb0ce91 Binary files /dev/null and b/release-notes/images/1_19/character-entities.png differ diff --git a/release-notes/images/1_19/edit-breakpoint.png b/release-notes/images/1_19/edit-breakpoint.png new file mode 100644 index 0000000000000000000000000000000000000000..97af3e5a2f17370edf3eec2d555a1a94c441a541 Binary files /dev/null and b/release-notes/images/1_19/edit-breakpoint.png differ diff --git a/release-notes/images/1_19/enable-extensions.png b/release-notes/images/1_19/enable-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..771f54c340d08df22adf52698161d9d0b79141cf Binary files /dev/null and b/release-notes/images/1_19/enable-extensions.png differ diff --git a/release-notes/images/1_19/image-diff.png b/release-notes/images/1_19/image-diff.png new file mode 100644 index 0000000000000000000000000000000000000000..bbca53c40650a904ff8f48db14c367458cdfa34e --- /dev/null +++ b/release-notes/images/1_19/image-diff.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e98619acb21d083df643871336d2cb3d83924d36a86085fbf84956883768e9bc +size 116548 diff --git a/release-notes/images/1_19/jsx-fragment.png b/release-notes/images/1_19/jsx-fragment.png new file mode 100644 index 0000000000000000000000000000000000000000..0a173bd70322baf9e30effaed20bdaa3fe85a105 Binary files /dev/null and b/release-notes/images/1_19/jsx-fragment.png differ diff --git a/release-notes/images/1_19/log-picker.png b/release-notes/images/1_19/log-picker.png new file mode 100644 index 0000000000000000000000000000000000000000..9b06473143f76e217a8cb92424f2f32082bd3679 Binary files /dev/null and b/release-notes/images/1_19/log-picker.png differ diff --git a/release-notes/images/1_19/release-highlights.png b/release-notes/images/1_19/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..813d9cb7117f331ebb7596a0d1eed1f4ddba9669 Binary files /dev/null and b/release-notes/images/1_19/release-highlights.png differ diff --git a/release-notes/images/1_19/running-extensions.png b/release-notes/images/1_19/running-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..a94eee996a26a196c7e2fd5a757b867e847a926c Binary files /dev/null and b/release-notes/images/1_19/running-extensions.png differ diff --git a/release-notes/images/1_19/shrink.gif b/release-notes/images/1_19/shrink.gif new file mode 100644 index 0000000000000000000000000000000000000000..1b6e50be7e2022bf4641b5908716c02f806b8d6d --- /dev/null +++ b/release-notes/images/1_19/shrink.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4243335b5b3988164261e44ed6ab08e0c6e5bb445b787d39b763a95f9a1cbfbc +size 286919 diff --git a/release-notes/images/1_19/status.png b/release-notes/images/1_19/status.png new file mode 100644 index 0000000000000000000000000000000000000000..966481453ff9b64fe58bc97469efc72565c82b32 --- /dev/null +++ b/release-notes/images/1_19/status.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9447650b56c97b4e2f98a249ea8ad083a5761d38417fb9bed71f1478e08b0acf +size 192776 diff --git a/release-notes/images/1_19/stdin.gif b/release-notes/images/1_19/stdin.gif new file mode 100644 index 0000000000000000000000000000000000000000..7487b7cee2545b8bfa701550a9cb79641fc0e77d --- /dev/null +++ b/release-notes/images/1_19/stdin.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cc04db530bc7510aa310aed53ab8c52ca0b271a0486570a7b9149f3557d0bf87 +size 328321 diff --git a/release-notes/images/1_19/suggest_mem.gif b/release-notes/images/1_19/suggest_mem.gif new file mode 100644 index 0000000000000000000000000000000000000000..08fff1fde3b51f73d24b52106b8f8c0093c484bb --- /dev/null +++ b/release-notes/images/1_19/suggest_mem.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:facd4ba31d1a8d35093e01a1e1c56ebba0906004a34a5cba444719ca13604e76 +size 348347 diff --git a/release-notes/images/1_19/suggest_relax.png b/release-notes/images/1_19/suggest_relax.png new file mode 100644 index 0000000000000000000000000000000000000000..b09293ebfb454e7c08a3cf357bf0b07d34219b7d Binary files /dev/null and b/release-notes/images/1_19/suggest_relax.png differ diff --git a/release-notes/images/1_19/synthetic-variables.png b/release-notes/images/1_19/synthetic-variables.png new file mode 100644 index 0000000000000000000000000000000000000000..430be4ffbfefabeaa63a3da0daa5b15c16074671 Binary files /dev/null and b/release-notes/images/1_19/synthetic-variables.png differ diff --git a/release-notes/images/1_19/vscode-processes.gif b/release-notes/images/1_19/vscode-processes.gif new file mode 100644 index 0000000000000000000000000000000000000000..45070de07a6193780c1d4dc7ab344a782c260ecb --- /dev/null +++ b/release-notes/images/1_19/vscode-processes.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bfbc1c65b06e67fe79262626036c6671f752d5af0bd468e135666852a9cf0d91 +size 3945192 diff --git a/release-notes/images/1_20/add-config.png b/release-notes/images/1_20/add-config.png new file mode 100644 index 0000000000000000000000000000000000000000..cc25ea4de346b7659910149cf966cdd0b12a2609 Binary files /dev/null and b/release-notes/images/1_20/add-config.png differ diff --git a/release-notes/images/1_20/auto-attach-cluster.gif b/release-notes/images/1_20/auto-attach-cluster.gif new file mode 100644 index 0000000000000000000000000000000000000000..2b5b658cb5b191f0416f4cfd9f8bcbe72a50d61c --- /dev/null +++ b/release-notes/images/1_20/auto-attach-cluster.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b0361034cadf75e3839ff5464990d6b6a356218c8a45919dd98fe3a77922f121 +size 13172866 diff --git a/release-notes/images/1_20/code-action-context-menu.png b/release-notes/images/1_20/code-action-context-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..98f6d13387ebf89f7a5758d93690c0064318e712 Binary files /dev/null and b/release-notes/images/1_20/code-action-context-menu.png differ diff --git a/release-notes/images/1_20/cursor-width.gif b/release-notes/images/1_20/cursor-width.gif new file mode 100644 index 0000000000000000000000000000000000000000..bba4fd14df8adb5dfcd5c2ea100dbbff663dae75 Binary files /dev/null and b/release-notes/images/1_20/cursor-width.gif differ diff --git a/release-notes/images/1_20/custom-file-view.png b/release-notes/images/1_20/custom-file-view.png new file mode 100644 index 0000000000000000000000000000000000000000..e287f6de63527f3ad7d76dd464e704f2e598980e Binary files /dev/null and b/release-notes/images/1_20/custom-file-view.png differ diff --git a/release-notes/images/1_20/custom-view-inline-action.png b/release-notes/images/1_20/custom-view-inline-action.png new file mode 100644 index 0000000000000000000000000000000000000000..91a83e952825e72ec86b6b9357da212ce5199fce Binary files /dev/null and b/release-notes/images/1_20/custom-view-inline-action.png differ diff --git a/release-notes/images/1_20/dropdown.png b/release-notes/images/1_20/dropdown.png new file mode 100644 index 0000000000000000000000000000000000000000..182776410b0956f1b974bd2910546b94ac3045e2 Binary files /dev/null and b/release-notes/images/1_20/dropdown.png differ diff --git a/release-notes/images/1_20/emmetprefix.gif b/release-notes/images/1_20/emmetprefix.gif new file mode 100644 index 0000000000000000000000000000000000000000..5bcb6593c008df316c577bef36077895e09b9c52 --- /dev/null +++ b/release-notes/images/1_20/emmetprefix.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:be7f2faaea50aa5a51d0233640885e2a2643cf265e57338a658a761f42d74648 +size 406361 diff --git a/release-notes/images/1_20/error-decoration.png b/release-notes/images/1_20/error-decoration.png new file mode 100644 index 0000000000000000000000000000000000000000..0816126253a82f5698ed18656bd7fe6b4a7378f4 Binary files /dev/null and b/release-notes/images/1_20/error-decoration.png differ diff --git a/release-notes/images/1_20/filerec.gif b/release-notes/images/1_20/filerec.gif new file mode 100644 index 0000000000000000000000000000000000000000..8c73d5a9451a7fb5ea98a51bfc887d8e74abb07f --- /dev/null +++ b/release-notes/images/1_20/filerec.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0817850b0eef43aeb0fb6692036121a31c83628db204ab3ebea5a6ed42ec9905 +size 1186079 diff --git a/release-notes/images/1_20/git-input-validation.gif b/release-notes/images/1_20/git-input-validation.gif new file mode 100644 index 0000000000000000000000000000000000000000..ea778fcc7d5f22b6fb258fc6f1309377a5b57c12 --- /dev/null +++ b/release-notes/images/1_20/git-input-validation.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:084c96356a625d5cd171b5beb8a3f3fceedf5059aeef325f56f9772019828d35 +size 1720485 diff --git a/release-notes/images/1_20/image-zoom.gif b/release-notes/images/1_20/image-zoom.gif new file mode 100644 index 0000000000000000000000000000000000000000..eedde1c55660c1fb93b3b8b07599faacd438dcad --- /dev/null +++ b/release-notes/images/1_20/image-zoom.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ae12028e9515a6b997882dddf94399b329c179f0110bdbfb561a38fbb1f54c98 +size 4516900 diff --git a/release-notes/images/1_20/issue_reporter.png b/release-notes/images/1_20/issue_reporter.png new file mode 100644 index 0000000000000000000000000000000000000000..1ee4d70a3e659fbf3478e024abcb22c54626ec79 Binary files /dev/null and b/release-notes/images/1_20/issue_reporter.png differ diff --git a/release-notes/images/1_20/language-pack.png b/release-notes/images/1_20/language-pack.png new file mode 100644 index 0000000000000000000000000000000000000000..cc6a1fd1ce8980895eaa1384ab661822a8b4a691 Binary files /dev/null and b/release-notes/images/1_20/language-pack.png differ diff --git a/release-notes/images/1_20/minimap-left-side.png b/release-notes/images/1_20/minimap-left-side.png new file mode 100644 index 0000000000000000000000000000000000000000..f072faf3f927b17b4f18fff80cccfb78a97cb855 --- /dev/null +++ b/release-notes/images/1_20/minimap-left-side.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3d0d96fa49abf0d1e75c8cd34c6dd71b001cf9a4bfc516580aba2cafa7dd1d03 +size 259818 diff --git a/release-notes/images/1_20/multi-select.gif b/release-notes/images/1_20/multi-select.gif new file mode 100644 index 0000000000000000000000000000000000000000..4b0fdb3f77fe8dc069b46d523fbebc08558e74ce --- /dev/null +++ b/release-notes/images/1_20/multi-select.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d919138b2392d08f1fc4cd3ab4273f2feb0907f7ff41eeab22bb5230729202ac +size 9154478 diff --git a/release-notes/images/1_20/notifications.png b/release-notes/images/1_20/notifications.png new file mode 100644 index 0000000000000000000000000000000000000000..530cfbf82fb7fa23286de0dbf4cf2185b2bb8c18 Binary files /dev/null and b/release-notes/images/1_20/notifications.png differ diff --git a/release-notes/images/1_20/output-log-channels.png b/release-notes/images/1_20/output-log-channels.png new file mode 100644 index 0000000000000000000000000000000000000000..b7a737c80cf18dae81e564fb5d3dd32e2f78add3 --- /dev/null +++ b/release-notes/images/1_20/output-log-channels.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1aff3e184f38117c8375cb21febd4721a0b3f2fe8d2d76c108deea6df6782e9e +size 210924 diff --git a/release-notes/images/1_20/popular-extension.png b/release-notes/images/1_20/popular-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..6811810a92410b0c8be7faefe7bd4f6cd65b7a06 --- /dev/null +++ b/release-notes/images/1_20/popular-extension.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:338dc25dea800f2a1548d180159ea46330b997af1ad9baff2c5f50d00df67153 +size 183059 diff --git a/release-notes/images/1_20/release-highlights.png b/release-notes/images/1_20/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..3efb43d1bdb46fbd12723afff68fb595599af23f Binary files /dev/null and b/release-notes/images/1_20/release-highlights.png differ diff --git a/release-notes/images/1_20/save_admin.gif b/release-notes/images/1_20/save_admin.gif new file mode 100644 index 0000000000000000000000000000000000000000..26e1dc40b7a1456299fde1fbb26026b7bb8db3aa --- /dev/null +++ b/release-notes/images/1_20/save_admin.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:533cea92bbe8615f2e62f5a8ef34254827fc07d07a0a32c3b2a9bc9bdf5f4bf4 +size 145525 diff --git a/release-notes/images/1_20/settings-search.png b/release-notes/images/1_20/settings-search.png new file mode 100644 index 0000000000000000000000000000000000000000..5079c9910f3b7802ba0a65c63e3845f4e548b30a Binary files /dev/null and b/release-notes/images/1_20/settings-search.png differ diff --git a/release-notes/images/1_20/submodules.png b/release-notes/images/1_20/submodules.png new file mode 100644 index 0000000000000000000000000000000000000000..5104bb9786ab5f3eb8c422ed57d6a17ccd76a4d7 --- /dev/null +++ b/release-notes/images/1_20/submodules.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8f8548b3423b4ed5c53124921a178b1fc02d15327e03da6d4e4820f10f21cba5 +size 117380 diff --git a/release-notes/images/1_20/tab_hover.gif b/release-notes/images/1_20/tab_hover.gif new file mode 100644 index 0000000000000000000000000000000000000000..56fc73f052d696f72b5d4fde54b3126e43ef82d1 --- /dev/null +++ b/release-notes/images/1_20/tab_hover.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3af01fb83c6bc10f94d60103ce4be44ce26116b067c9579f55c2d4e27cc41215 +size 666903 diff --git a/release-notes/images/1_20/toggle-ignore-trim-whitespace.gif b/release-notes/images/1_20/toggle-ignore-trim-whitespace.gif new file mode 100644 index 0000000000000000000000000000000000000000..db0632d99b4437e1f227f4ce42678e9c1149546d --- /dev/null +++ b/release-notes/images/1_20/toggle-ignore-trim-whitespace.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8cf27f2771ebc3bdab7511c02fdcb435d20af413ad65dbf70a9af41844ab37ae +size 1811444 diff --git a/release-notes/images/1_20/ts-auto-import-default.gif b/release-notes/images/1_20/ts-auto-import-default.gif new file mode 100644 index 0000000000000000000000000000000000000000..5561e3028ecc7c575a6aeb9a156af74083a7e277 --- /dev/null +++ b/release-notes/images/1_20/ts-auto-import-default.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:26152da0c0c1775cc8f615a4c35e6c14ca1bc25903c13c803dbcf9b6c3dc5ffa +size 1310287 diff --git a/release-notes/images/1_20/ts-bracket-post.png b/release-notes/images/1_20/ts-bracket-post.png new file mode 100644 index 0000000000000000000000000000000000000000..1f0e45c0f87e4ccf65c156013f83bb2b726cfca2 Binary files /dev/null and b/release-notes/images/1_20/ts-bracket-post.png differ diff --git a/release-notes/images/1_20/ts-bracket-pre.png b/release-notes/images/1_20/ts-bracket-pre.png new file mode 100644 index 0000000000000000000000000000000000000000..95c733242111250d47d45fd747e36393570574fd Binary files /dev/null and b/release-notes/images/1_20/ts-bracket-pre.png differ diff --git a/release-notes/images/1_20/ts-fix-all-in-file-post.png b/release-notes/images/1_20/ts-fix-all-in-file-post.png new file mode 100644 index 0000000000000000000000000000000000000000..ef8332cbc4bc299d4abfd3d754de2b047857df61 Binary files /dev/null and b/release-notes/images/1_20/ts-fix-all-in-file-post.png differ diff --git a/release-notes/images/1_20/ts-fix-all-in-file-pre.png b/release-notes/images/1_20/ts-fix-all-in-file-pre.png new file mode 100644 index 0000000000000000000000000000000000000000..064ead3353f701d786f7926a8f01d4eb55ef38e9 Binary files /dev/null and b/release-notes/images/1_20/ts-fix-all-in-file-pre.png differ diff --git a/release-notes/images/1_20/ts-optional-prop-completions.png b/release-notes/images/1_20/ts-optional-prop-completions.png new file mode 100644 index 0000000000000000000000000000000000000000..0d733004dfb883f23b3a9471c175d87729332490 Binary files /dev/null and b/release-notes/images/1_20/ts-optional-prop-completions.png differ diff --git a/release-notes/images/1_20/ts-styled-plugin.png b/release-notes/images/1_20/ts-styled-plugin.png new file mode 100644 index 0000000000000000000000000000000000000000..87eab8c9053ce8d03a1e975d33d1d94f4c45d50a Binary files /dev/null and b/release-notes/images/1_20/ts-styled-plugin.png differ diff --git a/release-notes/images/1_20/ts-this-dot-post.png b/release-notes/images/1_20/ts-this-dot-post.png new file mode 100644 index 0000000000000000000000000000000000000000..20fb48a5e649f2be3a1c948613d9bf2ac10cbf76 Binary files /dev/null and b/release-notes/images/1_20/ts-this-dot-post.png differ diff --git a/release-notes/images/1_20/ts-this-dot-pre.png b/release-notes/images/1_20/ts-this-dot-pre.png new file mode 100644 index 0000000000000000000000000000000000000000..161c55eaf9bc5ea3b1744d8623cfe0b14e4d4b2c Binary files /dev/null and b/release-notes/images/1_20/ts-this-dot-pre.png differ diff --git a/release-notes/images/1_20/workspace-settings.png b/release-notes/images/1_20/workspace-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..d8f0051d9c2f0be5cc0ee60d170fdf90e6d9aae0 Binary files /dev/null and b/release-notes/images/1_20/workspace-settings.png differ diff --git a/release-notes/images/1_21/activelinenumber.png b/release-notes/images/1_21/activelinenumber.png new file mode 100644 index 0000000000000000000000000000000000000000..58b30e3627fb9bf444576fc7e2b8fc888dd0baf4 Binary files /dev/null and b/release-notes/images/1_21/activelinenumber.png differ diff --git a/release-notes/images/1_21/breakpoints.png b/release-notes/images/1_21/breakpoints.png new file mode 100644 index 0000000000000000000000000000000000000000..64324407c3510291e45d5e9ec87e1b32e982d8c2 Binary files /dev/null and b/release-notes/images/1_21/breakpoints.png differ diff --git a/release-notes/images/1_21/centeredLayout.gif b/release-notes/images/1_21/centeredLayout.gif new file mode 100644 index 0000000000000000000000000000000000000000..ad954a9331eb8cfb3c65d35a7116355419fd8976 --- /dev/null +++ b/release-notes/images/1_21/centeredLayout.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:478f3fa55de3b8a950fbdf38790b84e75d55a4e7cb17f795f0f451aeea409c57 +size 3455299 diff --git a/release-notes/images/1_21/emmet-multi-filters.gif b/release-notes/images/1_21/emmet-multi-filters.gif new file mode 100644 index 0000000000000000000000000000000000000000..0c55897aeae9d19cc807a1eaa4274566bef972a9 Binary files /dev/null and b/release-notes/images/1_21/emmet-multi-filters.gif differ diff --git a/release-notes/images/1_21/emmet-style.gif b/release-notes/images/1_21/emmet-style.gif new file mode 100644 index 0000000000000000000000000000000000000000..8c166e80eb8a241c50d54cd9cbe87ebc9d82ee14 --- /dev/null +++ b/release-notes/images/1_21/emmet-style.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:90cd35b1e72f650823b2c55df9aaba0ac3580fd5feb3ade4aa223387d844fba0 +size 112772 diff --git a/release-notes/images/1_21/explorer-multiFolderCreation.gif b/release-notes/images/1_21/explorer-multiFolderCreation.gif new file mode 100644 index 0000000000000000000000000000000000000000..ed2bf321f33696d0a1ddad76a27bd391d5d6e1dc Binary files /dev/null and b/release-notes/images/1_21/explorer-multiFolderCreation.gif differ diff --git a/release-notes/images/1_21/issue-bot-duplicate-detection.png b/release-notes/images/1_21/issue-bot-duplicate-detection.png new file mode 100644 index 0000000000000000000000000000000000000000..4cca130ced3d1f92017d3e4ac0aa74e0f0e06201 Binary files /dev/null and b/release-notes/images/1_21/issue-bot-duplicate-detection.png differ diff --git a/release-notes/images/1_21/language-pack-extensions.png b/release-notes/images/1_21/language-pack-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..b9ea81d442922ed1bb26f80d3cf656887178d76d Binary files /dev/null and b/release-notes/images/1_21/language-pack-extensions.png differ diff --git a/release-notes/images/1_21/manage-builtin.gif b/release-notes/images/1_21/manage-builtin.gif new file mode 100644 index 0000000000000000000000000000000000000000..0ef295cbb36f004ace11a8f5915c0b7beaa29aa0 --- /dev/null +++ b/release-notes/images/1_21/manage-builtin.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:af09746a65f73fe2cf332ab7445a1a365d0b1f6a3e11c9498d2e756368e97fb1 +size 2650626 diff --git a/release-notes/images/1_21/md-dynamic-preview.gif b/release-notes/images/1_21/md-dynamic-preview.gif new file mode 100644 index 0000000000000000000000000000000000000000..0a19906f64c6140152ce95bef24b5651773f1a3a --- /dev/null +++ b/release-notes/images/1_21/md-dynamic-preview.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:641e8eaee50f74adf27424811780b8761f923f5f2ee3aa2aac0b92113fe7ad6c +size 1837109 diff --git a/release-notes/images/1_21/md-locked.png b/release-notes/images/1_21/md-locked.png new file mode 100644 index 0000000000000000000000000000000000000000..e04f5e53b9c6ffbaa60f1b66a7625f19a6cd8ae6 Binary files /dev/null and b/release-notes/images/1_21/md-locked.png differ diff --git a/release-notes/images/1_21/md-scroll-sync.gif b/release-notes/images/1_21/md-scroll-sync.gif new file mode 100644 index 0000000000000000000000000000000000000000..72512a5319dcd34af2c416ec244c5de9ffde9396 --- /dev/null +++ b/release-notes/images/1_21/md-scroll-sync.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9ea5a268122346e82ae221431fc53bcd8900cb09947e283a746c130bf9dc02f3 +size 3769713 diff --git a/release-notes/images/1_21/notification-small.png b/release-notes/images/1_21/notification-small.png new file mode 100644 index 0000000000000000000000000000000000000000..dcb1e9b6a1761ad32409b8de601c2a061fae4757 Binary files /dev/null and b/release-notes/images/1_21/notification-small.png differ diff --git a/release-notes/images/1_21/notification.png b/release-notes/images/1_21/notification.png new file mode 100644 index 0000000000000000000000000000000000000000..a53995472522e366f5707b5f77d8cd926c106a23 Binary files /dev/null and b/release-notes/images/1_21/notification.png differ diff --git a/release-notes/images/1_21/notifications.gif b/release-notes/images/1_21/notifications.gif new file mode 100644 index 0000000000000000000000000000000000000000..2dbe1eb083d824515ddcc2782585c4d7274af233 --- /dev/null +++ b/release-notes/images/1_21/notifications.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:befe8cfcfa25e805d638cdb7b390f8618807aca839d263fbcd9d63b681019737 +size 249672 diff --git a/release-notes/images/1_21/path-completion.gif b/release-notes/images/1_21/path-completion.gif new file mode 100644 index 0000000000000000000000000000000000000000..a3ef39ecf85642807b220617d702ac571f48e57e --- /dev/null +++ b/release-notes/images/1_21/path-completion.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8575347a3664cdd1cfece2e85b379b2ad5d82461a319f273524755b011c457ec +size 492090 diff --git a/release-notes/images/1_21/release-highlights.png b/release-notes/images/1_21/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..17fbd60325ab1e03352325a3f61b24e04922169a Binary files /dev/null and b/release-notes/images/1_21/release-highlights.png differ diff --git a/release-notes/images/1_21/search.png b/release-notes/images/1_21/search.png new file mode 100644 index 0000000000000000000000000000000000000000..67436b0398ce39564cd8ea2c6d624ba22a6cd4f7 --- /dev/null +++ b/release-notes/images/1_21/search.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a12dc133518e0dfcfe7b3843c9776af5060fa3cf165117d772a3ffadf509eb5f +size 136169 diff --git a/release-notes/images/1_21/symlink.png b/release-notes/images/1_21/symlink.png new file mode 100644 index 0000000000000000000000000000000000000000..76045ee42c63fce48be765ef34862d273e9cd3eb Binary files /dev/null and b/release-notes/images/1_21/symlink.png differ diff --git a/release-notes/images/1_21/terminal-split.gif b/release-notes/images/1_21/terminal-split.gif new file mode 100644 index 0000000000000000000000000000000000000000..f362766f9ff56ec0547b388ab2d0e7dda10e2bf0 --- /dev/null +++ b/release-notes/images/1_21/terminal-split.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2c06b5420caa8e81dda002fb000ae3af60bb13aa8ea68bdc6c30390a2e5d7ce1 +size 5774456 diff --git a/release-notes/images/1_21/window-copy-paste.gif b/release-notes/images/1_21/window-copy-paste.gif new file mode 100644 index 0000000000000000000000000000000000000000..e90f3ad6c31e08d664984e229eb087a1483362d4 --- /dev/null +++ b/release-notes/images/1_21/window-copy-paste.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8bbc2f445ec9833c9f553cb3518747cbec9523875ad3345acc83dff79c8a859c +size 567995 diff --git a/release-notes/images/1_21/window-dnd-files.gif b/release-notes/images/1_21/window-dnd-files.gif new file mode 100644 index 0000000000000000000000000000000000000000..919e7bba6fc7c35170f4653c7d3454c6e18641be --- /dev/null +++ b/release-notes/images/1_21/window-dnd-files.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7a6ae298b033c95d964d3155463190f91f4d11226d3fc25ece710299acbbea69 +size 884023 diff --git a/release-notes/images/1_22/auto-attach.gif b/release-notes/images/1_22/auto-attach.gif new file mode 100644 index 0000000000000000000000000000000000000000..0949a3d9a759dd40a7ce1ecacd7697b99a48984a --- /dev/null +++ b/release-notes/images/1_22/auto-attach.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6b87482ad595de9ef24c716aae61ab49ef8be781489d6d5336c631394e3020f5 +size 1241094 diff --git a/release-notes/images/1_22/css-path-completion.png b/release-notes/images/1_22/css-path-completion.png new file mode 100644 index 0000000000000000000000000000000000000000..2e0b97b663f917a5afba50c96e24d8a60060591d Binary files /dev/null and b/release-notes/images/1_22/css-path-completion.png differ diff --git a/release-notes/images/1_22/explorer-errors.png b/release-notes/images/1_22/explorer-errors.png new file mode 100644 index 0000000000000000000000000000000000000000..d75d7e2dfec4a8b9968151e8a63ed9ba38a33079 Binary files /dev/null and b/release-notes/images/1_22/explorer-errors.png differ diff --git a/release-notes/images/1_22/f8-navigation.gif b/release-notes/images/1_22/f8-navigation.gif new file mode 100644 index 0000000000000000000000000000000000000000..dda877f94975eb6838ad9e561ed574da1ca3403c --- /dev/null +++ b/release-notes/images/1_22/f8-navigation.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b1c7bbbeeab2bf6738667d0811caabb51df5ae49c7e1f012ca39c1fb14a639db +size 1860761 diff --git a/release-notes/images/1_22/large-file-notification.png b/release-notes/images/1_22/large-file-notification.png new file mode 100644 index 0000000000000000000000000000000000000000..2c815dc9d3af33d8907bb247d17c4728eca35caf Binary files /dev/null and b/release-notes/images/1_22/large-file-notification.png differ diff --git a/release-notes/images/1_22/log-points.gif b/release-notes/images/1_22/log-points.gif new file mode 100644 index 0000000000000000000000000000000000000000..2f692b52fc3d1ecd9f163c0b40f468b3559fbc9a --- /dev/null +++ b/release-notes/images/1_22/log-points.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dc80150db6320dc5cb14458bdde78c3dd0fd5a99fde28a75d019fa53455c33d8 +size 1582288 diff --git a/release-notes/images/1_22/long-running.gif b/release-notes/images/1_22/long-running.gif new file mode 100644 index 0000000000000000000000000000000000000000..3677abf8c905b3c2ac02f99dfbd4dae3a1f88118 Binary files /dev/null and b/release-notes/images/1_22/long-running.gif differ diff --git a/release-notes/images/1_22/markdown-folding.gif b/release-notes/images/1_22/markdown-folding.gif new file mode 100644 index 0000000000000000000000000000000000000000..09e3e96b040fbbaa587285fbd1298a29bacfa289 --- /dev/null +++ b/release-notes/images/1_22/markdown-folding.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:65646f60db97023f68f65a814921e12d011526565de98bce9fc70eb2f79f8f99 +size 3381211 diff --git a/release-notes/images/1_22/multi-select-quickpick.png b/release-notes/images/1_22/multi-select-quickpick.png new file mode 100644 index 0000000000000000000000000000000000000000..9284b65cc8766ae216325b419abbe19515005ce2 Binary files /dev/null and b/release-notes/images/1_22/multi-select-quickpick.png differ diff --git a/release-notes/images/1_22/process-picker.png b/release-notes/images/1_22/process-picker.png new file mode 100644 index 0000000000000000000000000000000000000000..388fe108253ceaf58044c6ee47259c0b0a937a41 Binary files /dev/null and b/release-notes/images/1_22/process-picker.png differ diff --git a/release-notes/images/1_22/references-f4.gif b/release-notes/images/1_22/references-f4.gif new file mode 100644 index 0000000000000000000000000000000000000000..be6dc5b6a82b78973406394da223d0e63d7fbe6f --- /dev/null +++ b/release-notes/images/1_22/references-f4.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:127f1b2593510babc8e367d8e1f3323aafafc715b4bca5c5a45147a0e214714a +size 3726381 diff --git a/release-notes/images/1_22/related-diagnostics-information.png b/release-notes/images/1_22/related-diagnostics-information.png new file mode 100644 index 0000000000000000000000000000000000000000..3e6b5a60c39811508321b69d3d49ce504289ea9e --- /dev/null +++ b/release-notes/images/1_22/related-diagnostics-information.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:380a66ba4014a0c2ff6f50f27531e3d980dec40660ef368f2f819380c747499d +size 112729 diff --git a/release-notes/images/1_22/release-highlights.png b/release-notes/images/1_22/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..74873326bfdbd1698881ddb51c3990741aa82c4a Binary files /dev/null and b/release-notes/images/1_22/release-highlights.png differ diff --git a/release-notes/images/1_22/report-on-extensions.png b/release-notes/images/1_22/report-on-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..fa9010a5026a0f7dcbf1cca7a80a921005a0d09c Binary files /dev/null and b/release-notes/images/1_22/report-on-extensions.png differ diff --git a/release-notes/images/1_22/save_part.gif b/release-notes/images/1_22/save_part.gif new file mode 100644 index 0000000000000000000000000000000000000000..91e065323d926715cadc58e1efcd63f40f6ece72 --- /dev/null +++ b/release-notes/images/1_22/save_part.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cfac1347220ca8ece7677c6bf236429cd11d6781dc2736121ea3a9015ac64a37 +size 820469 diff --git a/release-notes/images/1_22/search-patterns.png b/release-notes/images/1_22/search-patterns.png new file mode 100644 index 0000000000000000000000000000000000000000..09bbad9cdcd0350b08a37b14da987649d76eca29 Binary files /dev/null and b/release-notes/images/1_22/search-patterns.png differ diff --git a/release-notes/images/1_22/sev-hint.png b/release-notes/images/1_22/sev-hint.png new file mode 100644 index 0000000000000000000000000000000000000000..6662dcb91cbfc7e04482caaaf1178b69710d28c4 Binary files /dev/null and b/release-notes/images/1_22/sev-hint.png differ diff --git a/release-notes/images/1_22/syntax-fold.gif b/release-notes/images/1_22/syntax-fold.gif new file mode 100644 index 0000000000000000000000000000000000000000..d621850b8eacab904def544252aaabcfa9b42501 --- /dev/null +++ b/release-notes/images/1_22/syntax-fold.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8abac094cddbce3e81faa0b2a6418af77ae4b4b4e2118bac527325839890c78f +size 401033 diff --git a/release-notes/images/1_22/syntaxhighlight-optimization.gif b/release-notes/images/1_22/syntaxhighlight-optimization.gif new file mode 100644 index 0000000000000000000000000000000000000000..fcc4af423afe5a44ddb94ad6ad3f8bda1a46d96d --- /dev/null +++ b/release-notes/images/1_22/syntaxhighlight-optimization.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cdc26497d15d97f2d10e2578bed588aa7431266049d76a90bf44885b1d5d3d70 +size 805034 diff --git a/release-notes/images/1_22/terminal-command-tracking.gif b/release-notes/images/1_22/terminal-command-tracking.gif new file mode 100644 index 0000000000000000000000000000000000000000..e492df66778082ead1765d846e4459f22ad22d3e --- /dev/null +++ b/release-notes/images/1_22/terminal-command-tracking.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7e7e479995377ea4992fe288a8a24e693f0a687c41a83a35b914c46ab4d1a683 +size 2367914 diff --git a/release-notes/images/1_22/terminal-links.png b/release-notes/images/1_22/terminal-links.png new file mode 100644 index 0000000000000000000000000000000000000000..4027a9a1d96716a51226ed4a252b34c064e90916 Binary files /dev/null and b/release-notes/images/1_22/terminal-links.png differ diff --git a/release-notes/images/1_22/ts-jsdocs-quicksuggestions.gif b/release-notes/images/1_22/ts-jsdocs-quicksuggestions.gif new file mode 100644 index 0000000000000000000000000000000000000000..319f685ae134aa1a0bbf35320c72c26974cf2b07 --- /dev/null +++ b/release-notes/images/1_22/ts-jsdocs-quicksuggestions.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d34f909c4d398806154c1780c0b4883c7628b2a79a2883de6fd2e24f93a67dff +size 735037 diff --git a/release-notes/images/1_22/ts-organize-imports.gif b/release-notes/images/1_22/ts-organize-imports.gif new file mode 100644 index 0000000000000000000000000000000000000000..f3cbe94da08fedda24e9fbeaeb5756fa9739d6e0 --- /dev/null +++ b/release-notes/images/1_22/ts-organize-imports.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:26d8bebb8cf66fcd1113eda208df4fa00c182a53965874a3845c7bf94907e0de +size 2389566 diff --git a/release-notes/images/1_22/ts-suggestion-change.png b/release-notes/images/1_22/ts-suggestion-change.png new file mode 100644 index 0000000000000000000000000000000000000000..2739c6a9060198f4f00c1ff2bab3c26d393eee31 Binary files /dev/null and b/release-notes/images/1_22/ts-suggestion-change.png differ diff --git a/release-notes/images/1_22/ts-suggestion-click.png b/release-notes/images/1_22/ts-suggestion-click.png new file mode 100644 index 0000000000000000000000000000000000000000..a74a826c3c890b7800b37818972ad1188ff62939 Binary files /dev/null and b/release-notes/images/1_22/ts-suggestion-click.png differ diff --git a/release-notes/images/1_22/ts-suggestion-hover.png b/release-notes/images/1_22/ts-suggestion-hover.png new file mode 100644 index 0000000000000000000000000000000000000000..cf813a44d3b47b5f184ad3dceccd301da2a5c6a0 Binary files /dev/null and b/release-notes/images/1_22/ts-suggestion-hover.png differ diff --git a/release-notes/images/1_22/ts-suggestion-indicator.png b/release-notes/images/1_22/ts-suggestion-indicator.png new file mode 100644 index 0000000000000000000000000000000000000000..c4f16455cf6731c388925f9cf8089502384c6ebf Binary files /dev/null and b/release-notes/images/1_22/ts-suggestion-indicator.png differ diff --git a/release-notes/images/1_22/wrap.gif b/release-notes/images/1_22/wrap.gif new file mode 100644 index 0000000000000000000000000000000000000000..d2c3b4c748f108a69c9898975b945734140b671c --- /dev/null +++ b/release-notes/images/1_22/wrap.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:430f8f8e194be2526f90d9a3aa2195988b81ef8ba99d992fe99c6095477c7bed +size 150328 diff --git a/release-notes/images/1_23/SublimeSettingsImporter.gif b/release-notes/images/1_23/SublimeSettingsImporter.gif new file mode 100644 index 0000000000000000000000000000000000000000..50d0619f4dd8ca330ce9806934a1cb2a5e8694ea --- /dev/null +++ b/release-notes/images/1_23/SublimeSettingsImporter.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6f20720fa539a08571adb37446be76c4f0f14b471298386bd1b96f6f066d5701 +size 228701 diff --git a/release-notes/images/1_23/active-indent-guide.gif b/release-notes/images/1_23/active-indent-guide.gif new file mode 100644 index 0000000000000000000000000000000000000000..de0afc30d83df3a5bd80580a5bd3462d547457d8 --- /dev/null +++ b/release-notes/images/1_23/active-indent-guide.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:90ea434c917a79b882c86a8bc757e93af365240c7999b6f35c724699fec3dd07 +size 1667850 diff --git a/release-notes/images/1_23/azure-view.png b/release-notes/images/1_23/azure-view.png new file mode 100644 index 0000000000000000000000000000000000000000..c7a40979972461071af6d601bb6dd424c1e8f103 Binary files /dev/null and b/release-notes/images/1_23/azure-view.png differ diff --git a/release-notes/images/1_23/binary.png b/release-notes/images/1_23/binary.png new file mode 100644 index 0000000000000000000000000000000000000000..aef48bdce2305d386ae05bc65188ab2d49054185 Binary files /dev/null and b/release-notes/images/1_23/binary.png differ diff --git a/release-notes/images/1_23/copy-search.gif b/release-notes/images/1_23/copy-search.gif new file mode 100644 index 0000000000000000000000000000000000000000..a39497f523e265f79aecd52a2a9153b3969a8973 --- /dev/null +++ b/release-notes/images/1_23/copy-search.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:137850377f1f4c3f4bf10ff9f4a6d9f3513beba7b01645324ba6833aa94f5651 +size 3011740 diff --git a/release-notes/images/1_23/css-csstree.gif b/release-notes/images/1_23/css-csstree.gif new file mode 100644 index 0000000000000000000000000000000000000000..6f6addd182c6a309422dbe306ee0179c660ab710 --- /dev/null +++ b/release-notes/images/1_23/css-csstree.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:714f2342f8ded5159790b69a6f1f4d5f8ae3cf993bc85cd87d663526aec65925 +size 256393 diff --git a/release-notes/images/1_23/css-folding.gif b/release-notes/images/1_23/css-folding.gif new file mode 100644 index 0000000000000000000000000000000000000000..22a948fcf2f3619d10dd77417f8cf0a06dcb4930 --- /dev/null +++ b/release-notes/images/1_23/css-folding.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:265a208662d4806bb57ed4c07a36e4c2eae67c56a8a363a491d7bf472c9359c5 +size 165377 diff --git a/release-notes/images/1_23/css-mdn.gif b/release-notes/images/1_23/css-mdn.gif new file mode 100644 index 0000000000000000000000000000000000000000..8635fc9e24baacab60eff2bdd0d898bdf55fb775 --- /dev/null +++ b/release-notes/images/1_23/css-mdn.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d0b65ff8e13b3debe3a45a27f27a56d159bccdbc55606d2376eaa8cf120a9233 +size 1598949 diff --git a/release-notes/images/1_23/css-unkown-property.png b/release-notes/images/1_23/css-unkown-property.png new file mode 100644 index 0000000000000000000000000000000000000000..49e1fdcc61b84e3027663d92aabb617afe74fde0 Binary files /dev/null and b/release-notes/images/1_23/css-unkown-property.png differ diff --git a/release-notes/images/1_23/custom-view-scm.png b/release-notes/images/1_23/custom-view-scm.png new file mode 100644 index 0000000000000000000000000000000000000000..2ed5431e9127bcb35eb75485f2eddb886813ae65 Binary files /dev/null and b/release-notes/images/1_23/custom-view-scm.png differ diff --git a/release-notes/images/1_23/custom-views-container.png b/release-notes/images/1_23/custom-views-container.png new file mode 100644 index 0000000000000000000000000000000000000000..eaffdbdc4d76948ec7e427f1fd6ca8240fb2df73 Binary files /dev/null and b/release-notes/images/1_23/custom-views-container.png differ diff --git a/release-notes/images/1_23/editor-column-select.gif b/release-notes/images/1_23/editor-column-select.gif new file mode 100644 index 0000000000000000000000000000000000000000..ab056cefa4d0b21b9bd46bbac92a8a18b87d04aa --- /dev/null +++ b/release-notes/images/1_23/editor-column-select.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2b5b4ca74dade21ef3db8bf5b0328ee861a657b0d0a02261394956137a36bcf5 +size 1686531 diff --git a/release-notes/images/1_23/editor-stability.gif b/release-notes/images/1_23/editor-stability.gif new file mode 100644 index 0000000000000000000000000000000000000000..a7b20e332df967ee9ab88bf5c197ec3b30f1acb9 --- /dev/null +++ b/release-notes/images/1_23/editor-stability.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f861db8d40d6ebb2e1f3dc2513dfe7eb41ae958b63393a9ca65b2ceef3c1c7c6 +size 2846210 diff --git a/release-notes/images/1_23/fsp.png b/release-notes/images/1_23/fsp.png new file mode 100644 index 0000000000000000000000000000000000000000..47ef9388346cba49bf4540e8bbc57102a0bb8dbe --- /dev/null +++ b/release-notes/images/1_23/fsp.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8d42f9b9fda4b0c271de9c97b92528984669cb2f9ee2ae808d6aea56599093dd +size 105530 diff --git a/release-notes/images/1_23/logpoint-location.png b/release-notes/images/1_23/logpoint-location.png new file mode 100644 index 0000000000000000000000000000000000000000..884a0540db6281bdf6d1e174cc5c0b6d238ffe88 Binary files /dev/null and b/release-notes/images/1_23/logpoint-location.png differ diff --git a/release-notes/images/1_23/logpoints.gif b/release-notes/images/1_23/logpoints.gif new file mode 100644 index 0000000000000000000000000000000000000000..e1d2948c95d2dbc8738913bc586155eb552e58af --- /dev/null +++ b/release-notes/images/1_23/logpoints.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bb37aecff2dbb0b51ff98cc308823fefdeaf5d8976f479bf1bf879294d303f63 +size 179889 diff --git a/release-notes/images/1_23/markdown-restore.gif b/release-notes/images/1_23/markdown-restore.gif new file mode 100644 index 0000000000000000000000000000000000000000..d2d0a6f59320d15448da6838630690eacf66cc15 --- /dev/null +++ b/release-notes/images/1_23/markdown-restore.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:98d88f1717d2c3629a7a88b9c7a616081687a0c4ac227edef0c3d7f20caf734a +size 3379474 diff --git a/release-notes/images/1_23/markdown-workspace-symbol-search.png b/release-notes/images/1_23/markdown-workspace-symbol-search.png new file mode 100644 index 0000000000000000000000000000000000000000..c6a2bf9b4a787ba9ce971859cc7cc0e19e2e57f6 Binary files /dev/null and b/release-notes/images/1_23/markdown-workspace-symbol-search.png differ diff --git a/release-notes/images/1_23/open-view.png b/release-notes/images/1_23/open-view.png new file mode 100644 index 0000000000000000000000000000000000000000..cebc868f5c4fe93a70c0b3b2e1d830b027fd6c23 Binary files /dev/null and b/release-notes/images/1_23/open-view.png differ diff --git a/release-notes/images/1_23/problems_filter.gif b/release-notes/images/1_23/problems_filter.gif new file mode 100644 index 0000000000000000000000000000000000000000..8e92cdd960384f9192bf64d20a9dafe4da93523e --- /dev/null +++ b/release-notes/images/1_23/problems_filter.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a5dd004f4824a0c179a4a1a14e03aa7d633a1607bfe195e4d6d64d5aefcc213f +size 2606678 diff --git a/release-notes/images/1_23/process-explorer.gif b/release-notes/images/1_23/process-explorer.gif new file mode 100644 index 0000000000000000000000000000000000000000..69354316265b47a0ec6d4902131fb1e17f90aff6 --- /dev/null +++ b/release-notes/images/1_23/process-explorer.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4f0295c57f37be4c1a1280c3790807a1d81b491cba7ba649d98dd02f5fbea0c6 +size 235424 diff --git a/release-notes/images/1_23/release-highlights.png b/release-notes/images/1_23/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..071a055ca62bc9cf5b4f24d3109da59545f67e8e Binary files /dev/null and b/release-notes/images/1_23/release-highlights.png differ diff --git a/release-notes/images/1_23/script-explorer.png b/release-notes/images/1_23/script-explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..bf1a4076e385812e9c0dfe4629cf418595a1772a Binary files /dev/null and b/release-notes/images/1_23/script-explorer.png differ diff --git a/release-notes/images/1_23/search-include-exclude.png b/release-notes/images/1_23/search-include-exclude.png new file mode 100644 index 0000000000000000000000000000000000000000..e1ae88529802f3541f84cbc9f12fdbf8eab9a78a Binary files /dev/null and b/release-notes/images/1_23/search-include-exclude.png differ diff --git a/release-notes/images/1_23/test-views-container.png b/release-notes/images/1_23/test-views-container.png new file mode 100644 index 0000000000000000000000000000000000000000..c1b3aebee2925346761f8b5b70c01e89f39e19a9 Binary files /dev/null and b/release-notes/images/1_23/test-views-container.png differ diff --git a/release-notes/images/1_23/webview.png b/release-notes/images/1_23/webview.png new file mode 100644 index 0000000000000000000000000000000000000000..e8e147a6949784a841cbeec5bfe08829f699ed93 --- /dev/null +++ b/release-notes/images/1_23/webview.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:686667a12313d31ffe7c30d9d2ef31d05766a729e6e9c702362a845048f65179 +size 135389 diff --git a/release-notes/images/1_24/callstack.png b/release-notes/images/1_24/callstack.png new file mode 100644 index 0000000000000000000000000000000000000000..5e0f24a0fa1d24706fef7531d86f22137553e030 Binary files /dev/null and b/release-notes/images/1_24/callstack.png differ diff --git a/release-notes/images/1_24/continue.png b/release-notes/images/1_24/continue.png new file mode 100644 index 0000000000000000000000000000000000000000..194a72e9bb2deda1a687eeb3274f56b9e29e5d61 Binary files /dev/null and b/release-notes/images/1_24/continue.png differ diff --git a/release-notes/images/1_24/debug_toolbar.gif b/release-notes/images/1_24/debug_toolbar.gif new file mode 100644 index 0000000000000000000000000000000000000000..5ede108a7062beee8f3070e60c8d55ae14ec537a --- /dev/null +++ b/release-notes/images/1_24/debug_toolbar.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:35bbd4a091e7c581a19b268ffa1471b3e77d67cdfb5c70c660aef505f367b501 +size 1129605 diff --git a/release-notes/images/1_24/font-zoom.png b/release-notes/images/1_24/font-zoom.png new file mode 100644 index 0000000000000000000000000000000000000000..5900dcac430feaffbb3578e47246fb4c8e5f4433 Binary files /dev/null and b/release-notes/images/1_24/font-zoom.png differ diff --git a/release-notes/images/1_24/grid.gif b/release-notes/images/1_24/grid.gif new file mode 100644 index 0000000000000000000000000000000000000000..24ace69302226989d8b4e1c5bc62e5318fb2a20e --- /dev/null +++ b/release-notes/images/1_24/grid.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:091bbbe9f15c376e61e38eb0a628128b9f6e5b431331b65b6c4a6b2f9d1d1534 +size 4556658 diff --git a/release-notes/images/1_24/inline-diff-syntax.png b/release-notes/images/1_24/inline-diff-syntax.png new file mode 100644 index 0000000000000000000000000000000000000000..15cc67b947cdcec6c9aafaf1c99c7f76a60593e8 --- /dev/null +++ b/release-notes/images/1_24/inline-diff-syntax.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e5d9c6b3661ad692fdfcedad47de6a7bf0940968c8ee0b8f5e81ab8ef42f6837 +size 110647 diff --git a/release-notes/images/1_24/outline-all.png b/release-notes/images/1_24/outline-all.png new file mode 100644 index 0000000000000000000000000000000000000000..b2f3d4875d46dda51bb6539885e8db486eb0d846 --- /dev/null +++ b/release-notes/images/1_24/outline-all.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a70693ab8833234525b164ea614442922de970aff1df5e4fee57cda4895f9fbc +size 149043 diff --git a/release-notes/images/1_24/outline-enable.png b/release-notes/images/1_24/outline-enable.png new file mode 100644 index 0000000000000000000000000000000000000000..01a56820de8f0ea775bea50ffd68f5ebc941d2f5 Binary files /dev/null and b/release-notes/images/1_24/outline-enable.png differ diff --git a/release-notes/images/1_24/release-highlights.png b/release-notes/images/1_24/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..b6949632afc21a6055be44a88b3a6f371ce8af3b Binary files /dev/null and b/release-notes/images/1_24/release-highlights.png differ diff --git a/release-notes/images/1_24/scss-at.gif b/release-notes/images/1_24/scss-at.gif new file mode 100644 index 0000000000000000000000000000000000000000..94e8883f8d21407f4146468aa58322079f57247f --- /dev/null +++ b/release-notes/images/1_24/scss-at.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:afe52cba4f2d16de3731a762ef317fd79bb1ddd464d1e5a3eda2e2232ada2014 +size 375517 diff --git a/release-notes/images/1_24/settings-editor.gif b/release-notes/images/1_24/settings-editor.gif new file mode 100644 index 0000000000000000000000000000000000000000..1d9ef6275f6a4009d7473d1bf372432ccaa21bf2 --- /dev/null +++ b/release-notes/images/1_24/settings-editor.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d3e9e1cadef97c44ed78f60d2b39aad11a5b339aa28a0f9b16c554effb6dee4d +size 1070043 diff --git a/release-notes/images/1_24/terminal-dom-renderer.png b/release-notes/images/1_24/terminal-dom-renderer.png new file mode 100644 index 0000000000000000000000000000000000000000..0805fa966040b02bc40df944d91abaa227eaa51c Binary files /dev/null and b/release-notes/images/1_24/terminal-dom-renderer.png differ diff --git a/release-notes/images/1_24/terminal-italic.png b/release-notes/images/1_24/terminal-italic.png new file mode 100644 index 0000000000000000000000000000000000000000..1865be4b6db17dfaee40d706896a4df0ea2d0aa1 Binary files /dev/null and b/release-notes/images/1_24/terminal-italic.png differ diff --git a/release-notes/images/1_24/terminal-quick-open.png b/release-notes/images/1_24/terminal-quick-open.png new file mode 100644 index 0000000000000000000000000000000000000000..221907124de74fd5512beaf4de4b9901d010cc2b Binary files /dev/null and b/release-notes/images/1_24/terminal-quick-open.png differ diff --git a/release-notes/images/1_24/ts-generate-get-set-post.png b/release-notes/images/1_24/ts-generate-get-set-post.png new file mode 100644 index 0000000000000000000000000000000000000000..0d87e4a736ff3ff184418d776e17024cac495bff Binary files /dev/null and b/release-notes/images/1_24/ts-generate-get-set-post.png differ diff --git a/release-notes/images/1_24/ts-generate-get-set-pre.png b/release-notes/images/1_24/ts-generate-get-set-pre.png new file mode 100644 index 0000000000000000000000000000000000000000..8bba57104310277d10cc1eaa631a125fe8e0484e Binary files /dev/null and b/release-notes/images/1_24/ts-generate-get-set-pre.png differ diff --git a/release-notes/images/1_24/ts-grey-fix-all-action.png b/release-notes/images/1_24/ts-grey-fix-all-action.png new file mode 100644 index 0000000000000000000000000000000000000000..1bd2fe0dc1a4c88b20ad2fd642861187b1321011 Binary files /dev/null and b/release-notes/images/1_24/ts-grey-fix-all-action.png differ diff --git a/release-notes/images/1_24/ts-grey-post.png b/release-notes/images/1_24/ts-grey-post.png new file mode 100644 index 0000000000000000000000000000000000000000..6a405c672cda8f8ac13e098dc40d7e4eced9dca0 Binary files /dev/null and b/release-notes/images/1_24/ts-grey-post.png differ diff --git a/release-notes/images/1_24/ts-grey-pre.png b/release-notes/images/1_24/ts-grey-pre.png new file mode 100644 index 0000000000000000000000000000000000000000..22afd8a84b3fbccc155203f549f65507bf08edc8 Binary files /dev/null and b/release-notes/images/1_24/ts-grey-pre.png differ diff --git a/release-notes/images/1_24/ts-import-folding.gif b/release-notes/images/1_24/ts-import-folding.gif new file mode 100644 index 0000000000000000000000000000000000000000..a4c37d47d4279d6bf8c00833d09249b7b9d49d6c --- /dev/null +++ b/release-notes/images/1_24/ts-import-folding.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5924ccd29409e036eabaa2a8d41b69d6a11e38019992f7b15946f02f72fe62a0 +size 652743 diff --git a/release-notes/images/1_24/ts-move-to-file-post.png b/release-notes/images/1_24/ts-move-to-file-post.png new file mode 100644 index 0000000000000000000000000000000000000000..fce161ea365b6873a5b556bb41c5f0067c747729 --- /dev/null +++ b/release-notes/images/1_24/ts-move-to-file-post.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9ba828282fb685d090a290111d6ad685d5d7af43196a8f08b13e09365c3608c7 +size 106573 diff --git a/release-notes/images/1_24/ts-move-to-file-pre.png b/release-notes/images/1_24/ts-move-to-file-pre.png new file mode 100644 index 0000000000000000000000000000000000000000..8e8e851debff0d402717c60b59d5d0ed48433660 --- /dev/null +++ b/release-notes/images/1_24/ts-move-to-file-pre.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:414d0dc1c4a71916b284604569a25e9db20a40d7ec724b7f5559f103367e4f7d +size 199675 diff --git a/release-notes/images/1_24/ts-update-imports.gif b/release-notes/images/1_24/ts-update-imports.gif new file mode 100644 index 0000000000000000000000000000000000000000..c6e607b51a388f48dc467a4fbcdd6b4ac1c9dab4 --- /dev/null +++ b/release-notes/images/1_24/ts-update-imports.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5a3c236141f2178ae00602d8c79f66b5588cb7ba8241ad2c800e8c66e3180456 +size 5652244 diff --git a/release-notes/images/1_24/variables.png b/release-notes/images/1_24/variables.png new file mode 100644 index 0000000000000000000000000000000000000000..30c27610d91d65d8c912cf8141185d618c04cf23 Binary files /dev/null and b/release-notes/images/1_24/variables.png differ diff --git a/release-notes/images/1_24/vsts.png b/release-notes/images/1_24/vsts.png new file mode 100644 index 0000000000000000000000000000000000000000..0f76b8713492fff5f604e55cf2d971044967e7f8 Binary files /dev/null and b/release-notes/images/1_24/vsts.png differ diff --git a/release-notes/images/1_25/css-justify-items.png b/release-notes/images/1_25/css-justify-items.png new file mode 100644 index 0000000000000000000000000000000000000000..28544bb2c370a375f35a241f516da5ffa4658ed5 Binary files /dev/null and b/release-notes/images/1_25/css-justify-items.png differ diff --git a/release-notes/images/1_25/css-pseudo-selectors-elements.png b/release-notes/images/1_25/css-pseudo-selectors-elements.png new file mode 100644 index 0000000000000000000000000000000000000000..3b0bfad76f1218700c1e05721714c31ec94f9f7d Binary files /dev/null and b/release-notes/images/1_25/css-pseudo-selectors-elements.png differ diff --git a/release-notes/images/1_25/css-unknown-atrules.png b/release-notes/images/1_25/css-unknown-atrules.png new file mode 100644 index 0000000000000000000000000000000000000000..2cd3e82879cf65202b3588bef2a305f40cdb35f0 Binary files /dev/null and b/release-notes/images/1_25/css-unknown-atrules.png differ diff --git a/release-notes/images/1_25/custom_title.png b/release-notes/images/1_25/custom_title.png new file mode 100644 index 0000000000000000000000000000000000000000..f13c81fc487a9687065af8eaee992bab6a519ba1 Binary files /dev/null and b/release-notes/images/1_25/custom_title.png differ diff --git a/release-notes/images/1_25/debugtoolbar.gif b/release-notes/images/1_25/debugtoolbar.gif new file mode 100644 index 0000000000000000000000000000000000000000..ef5a434a3600b24ee18626f2eb77814e55692654 --- /dev/null +++ b/release-notes/images/1_25/debugtoolbar.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:63e168d5f131f234322084d706d61da3283b046c53830cf16491e4c12cd901b7 +size 215354 diff --git a/release-notes/images/1_25/defaultExtensionsView.gif b/release-notes/images/1_25/defaultExtensionsView.gif new file mode 100644 index 0000000000000000000000000000000000000000..218f6c42a66828f68d09a9c7553b420d3ecc78e9 --- /dev/null +++ b/release-notes/images/1_25/defaultExtensionsView.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1ec0976150dddc91e26ea526949764da2ebac300e2d2cd0918b0cd198c784a31 +size 500701 diff --git a/release-notes/images/1_25/defaultExtensionsView.png b/release-notes/images/1_25/defaultExtensionsView.png new file mode 100644 index 0000000000000000000000000000000000000000..e76d542319d75a9aa6eecd6de1679953685483cd Binary files /dev/null and b/release-notes/images/1_25/defaultExtensionsView.png differ diff --git a/release-notes/images/1_25/dismiss.gif b/release-notes/images/1_25/dismiss.gif new file mode 100644 index 0000000000000000000000000000000000000000..652c568244617e451cff5c232a3e049bf16bcf70 Binary files /dev/null and b/release-notes/images/1_25/dismiss.gif differ diff --git a/release-notes/images/1_25/drop.gif b/release-notes/images/1_25/drop.gif new file mode 100644 index 0000000000000000000000000000000000000000..c818634bc6dcf02e3b229f3e3bb96e72ad35205c --- /dev/null +++ b/release-notes/images/1_25/drop.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9156f0684f4e638c95f85376f622968b7b8501e6b0650b447ddc539eb9183b53 +size 549195 diff --git a/release-notes/images/1_25/editor-sub-word-navigation.gif b/release-notes/images/1_25/editor-sub-word-navigation.gif new file mode 100644 index 0000000000000000000000000000000000000000..90ed11d640beae8c3ffe801c4a91bd714abfa720 --- /dev/null +++ b/release-notes/images/1_25/editor-sub-word-navigation.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:72aad65f36d355612cfab8ed31906d3f4aef82594c4f91b683005fd3a818efd6 +size 826204 diff --git a/release-notes/images/1_25/editorPaneBackground.png b/release-notes/images/1_25/editorPaneBackground.png new file mode 100644 index 0000000000000000000000000000000000000000..cac06ac6846a84ba52def9ab0eff23c881457524 --- /dev/null +++ b/release-notes/images/1_25/editorPaneBackground.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5ab5ae4243fca70e0fc2c6a8198f19f226eb6cce08fc4638a35987683d2ff93a +size 149741 diff --git a/release-notes/images/1_25/grid-alt.gif b/release-notes/images/1_25/grid-alt.gif new file mode 100644 index 0000000000000000000000000000000000000000..347f2cda27c3665d6ee7d2760be900a1a19380de Binary files /dev/null and b/release-notes/images/1_25/grid-alt.gif differ diff --git a/release-notes/images/1_25/grid-background.png b/release-notes/images/1_25/grid-background.png new file mode 100644 index 0000000000000000000000000000000000000000..7816a38db189c4d5d4b25bb09d096f64114f369c Binary files /dev/null and b/release-notes/images/1_25/grid-background.png differ diff --git a/release-notes/images/1_25/grid-dnd.gif b/release-notes/images/1_25/grid-dnd.gif new file mode 100644 index 0000000000000000000000000000000000000000..24e3818df4f83e1e726126ed6d041cc9d8e97d52 --- /dev/null +++ b/release-notes/images/1_25/grid-dnd.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ef775fdc18f1bf362b6502b8bb94cac3680737d1a1904df9fcd59d3968e053de +size 156613 diff --git a/release-notes/images/1_25/grid-empty.png b/release-notes/images/1_25/grid-empty.png new file mode 100644 index 0000000000000000000000000000000000000000..eec9255cae0ea8776d260e913621593fb516fc13 Binary files /dev/null and b/release-notes/images/1_25/grid-empty.png differ diff --git a/release-notes/images/1_25/grid-layout-applied.png b/release-notes/images/1_25/grid-layout-applied.png new file mode 100644 index 0000000000000000000000000000000000000000..fb96b6f1eded20a2effa6d3982c7048e99c97e5c Binary files /dev/null and b/release-notes/images/1_25/grid-layout-applied.png differ diff --git a/release-notes/images/1_25/grid-layout-menu.png b/release-notes/images/1_25/grid-layout-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..b91808291e5f6aab03a7a0e5a7d77473046c42b6 Binary files /dev/null and b/release-notes/images/1_25/grid-layout-menu.png differ diff --git a/release-notes/images/1_25/grid-layout.gif b/release-notes/images/1_25/grid-layout.gif new file mode 100644 index 0000000000000000000000000000000000000000..82f95cf6116a552e9bae7a3c56f1c7764d87a6bd --- /dev/null +++ b/release-notes/images/1_25/grid-layout.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c24cee8bd7e61cf68f84c0cb5005f19cb927ad0f707d7af3aebffd8c12023c0b +size 2755469 diff --git a/release-notes/images/1_25/grid-numbering.png b/release-notes/images/1_25/grid-numbering.png new file mode 100644 index 0000000000000000000000000000000000000000..1738bd29be03d198a3df45671ff1cda99b1033d7 Binary files /dev/null and b/release-notes/images/1_25/grid-numbering.png differ diff --git a/release-notes/images/1_25/grid-open-editors.png b/release-notes/images/1_25/grid-open-editors.png new file mode 100644 index 0000000000000000000000000000000000000000..76f906f0fd99df1486399fbcb245c684013a771d Binary files /dev/null and b/release-notes/images/1_25/grid-open-editors.png differ diff --git a/release-notes/images/1_25/lang-pack-recommendation.png b/release-notes/images/1_25/lang-pack-recommendation.png new file mode 100644 index 0000000000000000000000000000000000000000..0b3bd418a0e5a64bfbf469fefb32f7e86c3618e9 Binary files /dev/null and b/release-notes/images/1_25/lang-pack-recommendation.png differ diff --git a/release-notes/images/1_25/lsp-inspector.gif b/release-notes/images/1_25/lsp-inspector.gif new file mode 100644 index 0000000000000000000000000000000000000000..cced0a89d854a14995f150a74015822a9e9eeab7 --- /dev/null +++ b/release-notes/images/1_25/lsp-inspector.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e41e96cab4624f82dfed5d17a5f1bdf931e40454194598dd82b7c1ae26b8451c +size 5924336 diff --git a/release-notes/images/1_25/md-outline.png b/release-notes/images/1_25/md-outline.png new file mode 100644 index 0000000000000000000000000000000000000000..8491e83588a429a4aab8335e8053ba8d4d11153f Binary files /dev/null and b/release-notes/images/1_25/md-outline.png differ diff --git a/release-notes/images/1_25/multistepinput.gif b/release-notes/images/1_25/multistepinput.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e45a73897bce1eb5ed1be48b4435319c1fcc280 --- /dev/null +++ b/release-notes/images/1_25/multistepinput.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:19653534786835987363481fa0089552530adb906b474bfc496a2432a8ebe1fe +size 627827 diff --git a/release-notes/images/1_25/outline.png b/release-notes/images/1_25/outline.png new file mode 100644 index 0000000000000000000000000000000000000000..122e92828c0f817d3384173289645c1e0e30cb1f Binary files /dev/null and b/release-notes/images/1_25/outline.png differ diff --git a/release-notes/images/1_25/release-highlights.png b/release-notes/images/1_25/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..6722934182b1a9cd6f35ab78463067707bb50900 Binary files /dev/null and b/release-notes/images/1_25/release-highlights.png differ diff --git a/release-notes/images/1_25/settings-editor.png b/release-notes/images/1_25/settings-editor.png new file mode 100644 index 0000000000000000000000000000000000000000..c1af0e9799606659af906bec246cd73df38bee61 --- /dev/null +++ b/release-notes/images/1_25/settings-editor.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4ececd31b569bba78c8a7c19e8a200ccc2cd9bb73501742e48bac43ac565bc4f +size 171700 diff --git a/release-notes/images/1_25/snippet_placeholder_transform.gif b/release-notes/images/1_25/snippet_placeholder_transform.gif new file mode 100644 index 0000000000000000000000000000000000000000..f92704526e005ece511280d978a6211ae1409aac --- /dev/null +++ b/release-notes/images/1_25/snippet_placeholder_transform.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:41c7229b95413f621655ecafcd7c0615cb3db1aa26fb1a231a9869124fbf8a1a +size 195547 diff --git a/release-notes/images/1_25/suggest_preselect.png b/release-notes/images/1_25/suggest_preselect.png new file mode 100644 index 0000000000000000000000000000000000000000..082264485143b9035ffba72e2467768bf935abab Binary files /dev/null and b/release-notes/images/1_25/suggest_preselect.png differ diff --git a/release-notes/images/1_26/appearance.png b/release-notes/images/1_26/appearance.png new file mode 100644 index 0000000000000000000000000000000000000000..24a38f60921bad91528718295a0d2c3e85c92785 Binary files /dev/null and b/release-notes/images/1_26/appearance.png differ diff --git a/release-notes/images/1_26/autosave.png b/release-notes/images/1_26/autosave.png new file mode 100644 index 0000000000000000000000000000000000000000..42306057f28b14c47acdb0b22dd9d561678c323c Binary files /dev/null and b/release-notes/images/1_26/autosave.png differ diff --git a/release-notes/images/1_26/breadcrumbs_active.gif b/release-notes/images/1_26/breadcrumbs_active.gif new file mode 100644 index 0000000000000000000000000000000000000000..6b30f14155aa0505764c0e81b3a2d2bdc067050b --- /dev/null +++ b/release-notes/images/1_26/breadcrumbs_active.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d2609cf551c0e848b378458d4388cc1d3315a1e4493fa44544811a22f6fae918 +size 1327506 diff --git a/release-notes/images/1_26/breadcrumbs_tabs_notabs.png b/release-notes/images/1_26/breadcrumbs_tabs_notabs.png new file mode 100644 index 0000000000000000000000000000000000000000..382f1c3a2bc041f26d93b1cb9aead34c57fe00b0 --- /dev/null +++ b/release-notes/images/1_26/breadcrumbs_tabs_notabs.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b2f8affda89291f4620f877b1520de39f1640aad503fe90268aa5fb26c053037 +size 132911 diff --git a/release-notes/images/1_26/customview-decorations.png b/release-notes/images/1_26/customview-decorations.png new file mode 100644 index 0000000000000000000000000000000000000000..17ab65c982ac3fbb5ce660b3e606122bd1e24256 Binary files /dev/null and b/release-notes/images/1_26/customview-decorations.png differ diff --git a/release-notes/images/1_26/exclude.png b/release-notes/images/1_26/exclude.png new file mode 100644 index 0000000000000000000000000000000000000000..8ffba45d7335814dd9f414acbc9c640c02b4de08 Binary files /dev/null and b/release-notes/images/1_26/exclude.png differ diff --git a/release-notes/images/1_26/extension-intellisense.gif b/release-notes/images/1_26/extension-intellisense.gif new file mode 100644 index 0000000000000000000000000000000000000000..b784cbf4c07906c3a6eebca3db5afc6725a35d8c --- /dev/null +++ b/release-notes/images/1_26/extension-intellisense.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:603d9ad01f20238bf80ee70667c113c08753eef12f85b42dd7e5903c5f3bde81 +size 180654 diff --git a/release-notes/images/1_26/extension-pack.png b/release-notes/images/1_26/extension-pack.png new file mode 100644 index 0000000000000000000000000000000000000000..813cb86dad47113f15899fe8659acadcbba93d11 Binary files /dev/null and b/release-notes/images/1_26/extension-pack.png differ diff --git a/release-notes/images/1_26/grid-maximize.gif b/release-notes/images/1_26/grid-maximize.gif new file mode 100644 index 0000000000000000000000000000000000000000..691d1fff9fe151b7e0e7a1ea8d570f963c645a71 --- /dev/null +++ b/release-notes/images/1_26/grid-maximize.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b8ec83b0c956ca66a0d4e0aeb852d52defa7270d22655c92b43005cd2f6d659a +size 2456880 diff --git a/release-notes/images/1_26/intellicode-extension.png b/release-notes/images/1_26/intellicode-extension.png new file mode 100644 index 0000000000000000000000000000000000000000..65c26d671af243a156c4effad7303963a885dc71 Binary files /dev/null and b/release-notes/images/1_26/intellicode-extension.png differ diff --git a/release-notes/images/1_26/multistepinput.gif b/release-notes/images/1_26/multistepinput.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e45a73897bce1eb5ed1be48b4435319c1fcc280 --- /dev/null +++ b/release-notes/images/1_26/multistepinput.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:19653534786835987363481fa0089552530adb906b474bfc496a2432a8ebe1fe +size 627827 diff --git a/release-notes/images/1_26/npm-script-hover.png b/release-notes/images/1_26/npm-script-hover.png new file mode 100644 index 0000000000000000000000000000000000000000..bc34ec68b13ca0a543b81e20ff5c02af6ac16a45 Binary files /dev/null and b/release-notes/images/1_26/npm-script-hover.png differ diff --git a/release-notes/images/1_26/open-folder-uri.png b/release-notes/images/1_26/open-folder-uri.png new file mode 100644 index 0000000000000000000000000000000000000000..5272abdb5ed0ed7dac5ef0997b28fe2a2dc89c01 --- /dev/null +++ b/release-notes/images/1_26/open-folder-uri.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a672a0473b9b2932e71195eb4258455477962fe7fd68166ef901466c1981ad1b +size 249548 diff --git a/release-notes/images/1_26/quickfix-problems.gif b/release-notes/images/1_26/quickfix-problems.gif new file mode 100644 index 0000000000000000000000000000000000000000..c7457c16870c49b9e0c6b281df5041e00189eb9a --- /dev/null +++ b/release-notes/images/1_26/quickfix-problems.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c844c50d47de5e801bfe421003edd838d5945c6e138ee4adf057986a3cb53dc6 +size 3805393 diff --git a/release-notes/images/1_26/rapid_render.gif b/release-notes/images/1_26/rapid_render.gif new file mode 100644 index 0000000000000000000000000000000000000000..4ad9f406eb3983a39b67f7e4a72cf6c215ef2523 --- /dev/null +++ b/release-notes/images/1_26/rapid_render.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c9d57acd41e346b8519800d05108d38703419223f28e630808c18407b003bd0b +size 490701 diff --git a/release-notes/images/1_26/release-highlights.png b/release-notes/images/1_26/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..f94835f7d81bef9b2eb76c5d24b3afff4b5cd4f5 Binary files /dev/null and b/release-notes/images/1_26/release-highlights.png differ diff --git a/release-notes/images/1_26/settings-editor.png b/release-notes/images/1_26/settings-editor.png new file mode 100644 index 0000000000000000000000000000000000000000..b62475a607fa4429c2c56b254a72a634442aa0b3 --- /dev/null +++ b/release-notes/images/1_26/settings-editor.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7b314900a874433465f0fe83b01396cc79580a6de4138c2afffb2b043f254202 +size 186030 diff --git a/release-notes/images/1_26/terminal-column-selection.png b/release-notes/images/1_26/terminal-column-selection.png new file mode 100644 index 0000000000000000000000000000000000000000..fb965ce91ce9bbe5cd1cad962ecbe8ee4cce560b --- /dev/null +++ b/release-notes/images/1_26/terminal-column-selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:94027953e03eb450ae2e4917c75c18452a77787fb75ae36bb4cade2f6a7446e3 +size 145736 diff --git a/release-notes/images/1_26/theme_menus.png b/release-notes/images/1_26/theme_menus.png new file mode 100644 index 0000000000000000000000000000000000000000..b7eda4df8222b34791499e8d029f9a1184cc4b8f Binary files /dev/null and b/release-notes/images/1_26/theme_menus.png differ diff --git a/release-notes/images/1_26/ts-28-bad-error.png b/release-notes/images/1_26/ts-28-bad-error.png new file mode 100644 index 0000000000000000000000000000000000000000..3b451eef5f754cbe0c45294472ec4c4215f318d1 Binary files /dev/null and b/release-notes/images/1_26/ts-28-bad-error.png differ diff --git a/release-notes/images/1_26/ts-30-better-error.png b/release-notes/images/1_26/ts-30-better-error.png new file mode 100644 index 0000000000000000000000000000000000000000..8f48f7c4988c869ee06fa753822200b4802a6b9e Binary files /dev/null and b/release-notes/images/1_26/ts-30-better-error.png differ diff --git a/release-notes/images/1_26/ts-convert-to-namespace-import.gif b/release-notes/images/1_26/ts-convert-to-namespace-import.gif new file mode 100644 index 0000000000000000000000000000000000000000..23b3854e8b2af722ac0d08d0c8214ddea791b3ad --- /dev/null +++ b/release-notes/images/1_26/ts-convert-to-namespace-import.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:89301febc2aa42611a851fc5dbdccf2a231f7eeccc9c182e8e60983248ba7604 +size 4222777 diff --git a/release-notes/images/1_26/ts-import-all-quick-fix.gif b/release-notes/images/1_26/ts-import-all-quick-fix.gif new file mode 100644 index 0000000000000000000000000000000000000000..4c194e75f881a48b3673ca12a5f2e47f19fbb0f5 --- /dev/null +++ b/release-notes/images/1_26/ts-import-all-quick-fix.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5f3737277317cd0cc2e28a7169ca35fcd8c368fcf0f08d67e4017ca7ac204937 +size 2658411 diff --git a/release-notes/images/1_26/ts-jsx-folding.gif b/release-notes/images/1_26/ts-jsx-folding.gif new file mode 100644 index 0000000000000000000000000000000000000000..311a1c6f853eedd333b0a04ae2a46488d9a4ab0e --- /dev/null +++ b/release-notes/images/1_26/ts-jsx-folding.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a9bc2a96c50224fde54038d8b2a90a7d5c46224fb05951468446c614c324f231 +size 1797999 diff --git a/release-notes/images/1_26/ts-jsx-tag-complete.gif b/release-notes/images/1_26/ts-jsx-tag-complete.gif new file mode 100644 index 0000000000000000000000000000000000000000..91de177e5ba9f595f36e7ea5b9f9335a79e58a29 --- /dev/null +++ b/release-notes/images/1_26/ts-jsx-tag-complete.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c07058bb71b3c2babd96f4769273c9814d52f73e8e7cc906324b2560a1785d80 +size 1395356 diff --git a/release-notes/images/1_26/ts-related-diagnostic.png b/release-notes/images/1_26/ts-related-diagnostic.png new file mode 100644 index 0000000000000000000000000000000000000000..f9e82f90e8748ab8344b0b6d512bb03e91c5ccf5 Binary files /dev/null and b/release-notes/images/1_26/ts-related-diagnostic.png differ diff --git a/release-notes/images/1_26/ts-tsconfig-path-click.png b/release-notes/images/1_26/ts-tsconfig-path-click.png new file mode 100644 index 0000000000000000000000000000000000000000..0d52a8c1b37f922c895007263f378f11cea61898 Binary files /dev/null and b/release-notes/images/1_26/ts-tsconfig-path-click.png differ diff --git a/release-notes/images/1_26/webview-icon.png b/release-notes/images/1_26/webview-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..f9cbe083dd22f6fe51e2393cd639e466ad8fe873 --- /dev/null +++ b/release-notes/images/1_26/webview-icon.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b34fa9142b081d3e608bb1b59d5ea093f051cc955c40b8b616f855d52e5b0e05 +size 140124 diff --git a/release-notes/images/1_27/aligned-multiple.png b/release-notes/images/1_27/aligned-multiple.png new file mode 100644 index 0000000000000000000000000000000000000000..798fb99816710ee178316b9af7a3ab7e8b65f8bb Binary files /dev/null and b/release-notes/images/1_27/aligned-multiple.png differ diff --git a/release-notes/images/1_27/comments_panel.png b/release-notes/images/1_27/comments_panel.png new file mode 100644 index 0000000000000000000000000000000000000000..b9f7f3fbd5d1c0a731b23c9bd25e3af6c47ba608 Binary files /dev/null and b/release-notes/images/1_27/comments_panel.png differ diff --git a/release-notes/images/1_27/css-definition.gif b/release-notes/images/1_27/css-definition.gif new file mode 100644 index 0000000000000000000000000000000000000000..6c06ad390cec83168640d3bed3d738372f7dce96 --- /dev/null +++ b/release-notes/images/1_27/css-definition.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9f78a62e4ae1c8e8e99d31f20ba578a4e35a889b9a3f724d0031712dc4573387 +size 3739254 diff --git a/release-notes/images/1_27/css-import.gif b/release-notes/images/1_27/css-import.gif new file mode 100644 index 0000000000000000000000000000000000000000..bcbe98cc920393346ba68725aa4121604cd7ceda --- /dev/null +++ b/release-notes/images/1_27/css-import.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:25c3c258b807add943951439be266107b8ec852c2113f51badeb3f21df044c3f +size 1547865 diff --git a/release-notes/images/1_27/custom_tb_menus.png b/release-notes/images/1_27/custom_tb_menus.png new file mode 100644 index 0000000000000000000000000000000000000000..5a680654a2bf66297f68145209975d51b42b9748 Binary files /dev/null and b/release-notes/images/1_27/custom_tb_menus.png differ diff --git a/release-notes/images/1_27/deleted-from-disk.png b/release-notes/images/1_27/deleted-from-disk.png new file mode 100644 index 0000000000000000000000000000000000000000..8230bae0819f96670cb0fffb1598e81da13f215d Binary files /dev/null and b/release-notes/images/1_27/deleted-from-disk.png differ diff --git a/release-notes/images/1_27/document_comment.png b/release-notes/images/1_27/document_comment.png new file mode 100644 index 0000000000000000000000000000000000000000..e4d97e5326902b263e076ebd97ac00edef865272 Binary files /dev/null and b/release-notes/images/1_27/document_comment.png differ diff --git a/release-notes/images/1_27/dropdown.png b/release-notes/images/1_27/dropdown.png new file mode 100644 index 0000000000000000000000000000000000000000..49d43a698964959fc99ed5a6ecc3506971facc4f Binary files /dev/null and b/release-notes/images/1_27/dropdown.png differ diff --git a/release-notes/images/1_27/extension-settings.png b/release-notes/images/1_27/extension-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..9bd6fd505c06a8141fa5c0feb7b148e8b499564f --- /dev/null +++ b/release-notes/images/1_27/extension-settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6317e8e804c7df832240b39a6faeca64841fb80afeeae7d9f4e8c6857ae67417 +size 112441 diff --git a/release-notes/images/1_27/github_pull_requests.gif b/release-notes/images/1_27/github_pull_requests.gif new file mode 100644 index 0000000000000000000000000000000000000000..0006f4c07c650f9aed8a87c93e36167f4aa0dbd3 --- /dev/null +++ b/release-notes/images/1_27/github_pull_requests.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b6f26a917e93eb7b05d2e3e1ae8c06dc12739923f572af5bc8de3b156915844f +size 7210566 diff --git a/release-notes/images/1_27/log-streaming.gif b/release-notes/images/1_27/log-streaming.gif new file mode 100644 index 0000000000000000000000000000000000000000..774a8f05d5d830c3e22bae9b2556416a4cf53ac9 --- /dev/null +++ b/release-notes/images/1_27/log-streaming.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8a4735ccc429e3d2cc60c127cce01e1768f66f4aacfecb9549ab4ac8a45c8459 +size 6717159 diff --git a/release-notes/images/1_27/modified-and-contextmenu.png b/release-notes/images/1_27/modified-and-contextmenu.png new file mode 100644 index 0000000000000000000000000000000000000000..f649bd5703c5528c3c7a6f2b1be5d7a9372b3450 Binary files /dev/null and b/release-notes/images/1_27/modified-and-contextmenu.png differ diff --git a/release-notes/images/1_27/picker-highlights.gif b/release-notes/images/1_27/picker-highlights.gif new file mode 100644 index 0000000000000000000000000000000000000000..8332d5bebeb90b356824f6d178d2f0dcb5220565 --- /dev/null +++ b/release-notes/images/1_27/picker-highlights.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:92be13f1631ce25d2807dd0dc0c7ca43f170f0a663475fb21b1c320b875c9c76 +size 3019625 diff --git a/release-notes/images/1_27/release-highlights.png b/release-notes/images/1_27/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..8b194d1acd8805df9ed4b4abf69a97b7d4e9267d Binary files /dev/null and b/release-notes/images/1_27/release-highlights.png differ diff --git a/release-notes/images/1_27/search-filter.gif b/release-notes/images/1_27/search-filter.gif new file mode 100644 index 0000000000000000000000000000000000000000..373b100ab5210e81150a66f30f9b4875cabc7a84 --- /dev/null +++ b/release-notes/images/1_27/search-filter.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b50f598f3185584a4013e986ffc10dfe1d087eb34b21b1b9333f433842893bf8 +size 446610 diff --git a/release-notes/images/1_27/settings-editor.png b/release-notes/images/1_27/settings-editor.png new file mode 100644 index 0000000000000000000000000000000000000000..664f0fa2c768fe29722a25b2b100331b1629d065 Binary files /dev/null and b/release-notes/images/1_27/settings-editor.png differ diff --git a/release-notes/images/1_27/settings-validation.png b/release-notes/images/1_27/settings-validation.png new file mode 100644 index 0000000000000000000000000000000000000000..484fe706f07c4de862b26d142c558fa4999915e2 Binary files /dev/null and b/release-notes/images/1_27/settings-validation.png differ diff --git a/release-notes/images/1_27/terminal-menu.png b/release-notes/images/1_27/terminal-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..6faa2d61d2e07092875c6c7c7d0dcbb793dccf3e Binary files /dev/null and b/release-notes/images/1_27/terminal-menu.png differ diff --git a/release-notes/images/1_28/comment_edit.gif b/release-notes/images/1_28/comment_edit.gif new file mode 100644 index 0000000000000000000000000000000000000000..6af7029f96c85b20ba2f954a54e52f3a09740340 --- /dev/null +++ b/release-notes/images/1_28/comment_edit.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ed759fa9217a3d82662c9bbe181518c1f5778584217f70ea795d7e536c430371 +size 214260 diff --git a/release-notes/images/1_28/copy-relative-path.png b/release-notes/images/1_28/copy-relative-path.png new file mode 100644 index 0000000000000000000000000000000000000000..372f79d24cf79683b0b454af2d58d0653e98fc59 Binary files /dev/null and b/release-notes/images/1_28/copy-relative-path.png differ diff --git a/release-notes/images/1_28/custom-view-focus-commands.png b/release-notes/images/1_28/custom-view-focus-commands.png new file mode 100644 index 0000000000000000000000000000000000000000..a50e46bfbf6b0c0abf806ddcb2f3809b1ff18666 Binary files /dev/null and b/release-notes/images/1_28/custom-view-focus-commands.png differ diff --git a/release-notes/images/1_28/custom_menus.png b/release-notes/images/1_28/custom_menus.png new file mode 100644 index 0000000000000000000000000000000000000000..f81f1d8197afec96cf695f137a5b5861a4a5576c Binary files /dev/null and b/release-notes/images/1_28/custom_menus.png differ diff --git a/release-notes/images/1_28/deleted.gif b/release-notes/images/1_28/deleted.gif new file mode 100644 index 0000000000000000000000000000000000000000..78cffc417b0256057a2d050fec446f98c2fd9940 --- /dev/null +++ b/release-notes/images/1_28/deleted.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c9355dfaf059dbe4e6609cf2fa717245ee5b3522a0b3a36bb3f754ac1b5171ad +size 320475 diff --git a/release-notes/images/1_28/extension-host-unresponsive.png b/release-notes/images/1_28/extension-host-unresponsive.png new file mode 100644 index 0000000000000000000000000000000000000000..41c856c0d5c2443b62952c01d3578f77d7acd302 Binary files /dev/null and b/release-notes/images/1_28/extension-host-unresponsive.png differ diff --git a/release-notes/images/1_28/file-icons.png b/release-notes/images/1_28/file-icons.png new file mode 100644 index 0000000000000000000000000000000000000000..01ea801666a61f7074b0147c1768b4eeb06a7602 Binary files /dev/null and b/release-notes/images/1_28/file-icons.png differ diff --git a/release-notes/images/1_28/locality-bonus.png b/release-notes/images/1_28/locality-bonus.png new file mode 100644 index 0000000000000000000000000000000000000000..a95effccbb798a99d96489159e7b5768bb7e2ebd Binary files /dev/null and b/release-notes/images/1_28/locality-bonus.png differ diff --git a/release-notes/images/1_28/markdown-folding.gif b/release-notes/images/1_28/markdown-folding.gif new file mode 100644 index 0000000000000000000000000000000000000000..a5e688da99da9097179b3cef4856b415e93609c5 --- /dev/null +++ b/release-notes/images/1_28/markdown-folding.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7792453cac7671bfa03eb33b551e10f032e3773c81cc0500038e2c0a24e7524e +size 3404216 diff --git a/release-notes/images/1_28/markdown-preview-link.gif b/release-notes/images/1_28/markdown-preview-link.gif new file mode 100644 index 0000000000000000000000000000000000000000..b78cd40bd03603a6de6f8cc1dc4c9891f4439ce6 --- /dev/null +++ b/release-notes/images/1_28/markdown-preview-link.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:981760ed03b761a694ea9a132c99e92704146d9808be1a5228b662be481ac251 +size 2535949 diff --git a/release-notes/images/1_28/problem-code.png b/release-notes/images/1_28/problem-code.png new file mode 100644 index 0000000000000000000000000000000000000000..dd17ca7b9c7eb334c7d1b2973d322d53c4450659 Binary files /dev/null and b/release-notes/images/1_28/problem-code.png differ diff --git a/release-notes/images/1_28/project-snippet.jpg b/release-notes/images/1_28/project-snippet.jpg new file mode 100644 index 0000000000000000000000000000000000000000..669764642636a0a3475a013e8818be9ea10dcd8c Binary files /dev/null and b/release-notes/images/1_28/project-snippet.jpg differ diff --git a/release-notes/images/1_28/record-keybindings.gif b/release-notes/images/1_28/record-keybindings.gif new file mode 100644 index 0000000000000000000000000000000000000000..f4c4a9adc8dd3ff853c6353c985045c1c92b83eb --- /dev/null +++ b/release-notes/images/1_28/record-keybindings.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a7274f3d1a54f03f0b05d9fea179871d4b2c96bc7893be0ed9643b8bac06e8ce +size 904825 diff --git a/release-notes/images/1_28/release-highlights.png b/release-notes/images/1_28/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..130ae3a78f73395a18a755e654a0de5d908b5826 Binary files /dev/null and b/release-notes/images/1_28/release-highlights.png differ diff --git a/release-notes/images/1_28/september-issue-grooming-1.png b/release-notes/images/1_28/september-issue-grooming-1.png new file mode 100644 index 0000000000000000000000000000000000000000..bbea23037ad4865f3bdb1b72d0ebc28698fa857f Binary files /dev/null and b/release-notes/images/1_28/september-issue-grooming-1.png differ diff --git a/release-notes/images/1_28/september-issue-grooming-2.png b/release-notes/images/1_28/september-issue-grooming-2.png new file mode 100644 index 0000000000000000000000000000000000000000..ba16a8e3c5dfeaf849006bb5aa5c351a3bd6824b Binary files /dev/null and b/release-notes/images/1_28/september-issue-grooming-2.png differ diff --git a/release-notes/images/1_28/staged.png b/release-notes/images/1_28/staged.png new file mode 100644 index 0000000000000000000000000000000000000000..0513ccf23e840bfc2ecad18726f94a27f6211d46 Binary files /dev/null and b/release-notes/images/1_28/staged.png differ diff --git a/release-notes/images/1_28/tabcompletion.gif b/release-notes/images/1_28/tabcompletion.gif new file mode 100644 index 0000000000000000000000000000000000000000..26bbfaa7e5ae0ac2592beafda41f6115761612b8 --- /dev/null +++ b/release-notes/images/1_28/tabcompletion.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:21b6b2b19596ede078a0659dfcf967cf6a3804fb0c3863fc221a335d189983ae +size 389167 diff --git a/release-notes/images/1_28/ts-convert-to-async.gif b/release-notes/images/1_28/ts-convert-to-async.gif new file mode 100644 index 0000000000000000000000000000000000000000..15531767e2b273f25780e2b5a674a1121a232a94 --- /dev/null +++ b/release-notes/images/1_28/ts-convert-to-async.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3993146257cdac36279a25c9094f6e9a59be6abdbeb1663c7dd3d9c18026b24e +size 1679630 diff --git a/release-notes/images/1_28/ts-rename-import.gif b/release-notes/images/1_28/ts-rename-import.gif new file mode 100644 index 0000000000000000000000000000000000000000..62dc99219efb24c5b3a93a8320f176273917b42e --- /dev/null +++ b/release-notes/images/1_28/ts-rename-import.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c71374e3f2247523dd86ad86216d348a4d4fb959d1f19ee74ad35155475bea82 +size 1560264 diff --git a/release-notes/images/1_28/workspace-prompt.png b/release-notes/images/1_28/workspace-prompt.png new file mode 100644 index 0000000000000000000000000000000000000000..4abb93da1b4e692150d16e0464d6b234fb682308 Binary files /dev/null and b/release-notes/images/1_28/workspace-prompt.png differ diff --git a/release-notes/images/1_29/breadcrumb-order.png b/release-notes/images/1_29/breadcrumb-order.png new file mode 100644 index 0000000000000000000000000000000000000000..b01f982b6ab5aec9168f92cd5ca7c4d78b8e7b9c Binary files /dev/null and b/release-notes/images/1_29/breadcrumb-order.png differ diff --git a/release-notes/images/1_29/breakpoint-widget.png b/release-notes/images/1_29/breakpoint-widget.png new file mode 100644 index 0000000000000000000000000000000000000000..160e9dc39b669decc8695070b9f2939e60d5f05d Binary files /dev/null and b/release-notes/images/1_29/breakpoint-widget.png differ diff --git a/release-notes/images/1_29/completion-file-icons.png b/release-notes/images/1_29/completion-file-icons.png new file mode 100644 index 0000000000000000000000000000000000000000..fcf7762ce7ff8902dd391b0673dfe742a5ec18a4 Binary files /dev/null and b/release-notes/images/1_29/completion-file-icons.png differ diff --git a/release-notes/images/1_29/console-styles.png b/release-notes/images/1_29/console-styles.png new file mode 100644 index 0000000000000000000000000000000000000000..2a196d015939960feb62880672881bdb20410633 Binary files /dev/null and b/release-notes/images/1_29/console-styles.png differ diff --git a/release-notes/images/1_29/css-specificity.png b/release-notes/images/1_29/css-specificity.png new file mode 100644 index 0000000000000000000000000000000000000000..d73fcae8e217cf113370f29cac5bcd7347db2021 Binary files /dev/null and b/release-notes/images/1_29/css-specificity.png differ diff --git a/release-notes/images/1_29/error-code.png b/release-notes/images/1_29/error-code.png new file mode 100644 index 0000000000000000000000000000000000000000..4c1881f32a896589ff7bd3ea58cded7365475c57 Binary files /dev/null and b/release-notes/images/1_29/error-code.png differ diff --git a/release-notes/images/1_29/file-icon-preview.gif b/release-notes/images/1_29/file-icon-preview.gif new file mode 100644 index 0000000000000000000000000000000000000000..3a746bc67ab3e5e0cacc7abd940dfc8601d0ff1e --- /dev/null +++ b/release-notes/images/1_29/file-icon-preview.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5e3f215515d9148b4b393d87ba08fa0af08c178afd17357f8a60057a7e9a0b6a +size 168654 diff --git a/release-notes/images/1_29/highlight-modified-tabs.gif b/release-notes/images/1_29/highlight-modified-tabs.gif new file mode 100644 index 0000000000000000000000000000000000000000..99035bf95aa7fcaaa57ab61b80b5577f2e202dae --- /dev/null +++ b/release-notes/images/1_29/highlight-modified-tabs.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a691352fec005d7fb2a2305f99ea59e3c50fc9353ea2aa49bdd9fecfeae6d581 +size 1056798 diff --git a/release-notes/images/1_29/json-schema-loading.gif b/release-notes/images/1_29/json-schema-loading.gif new file mode 100644 index 0000000000000000000000000000000000000000..bce9e900c505215a77e0ca01bbb23e944b937305 --- /dev/null +++ b/release-notes/images/1_29/json-schema-loading.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a1542d8102d05844acc8e67dac60107a3a558e2862beb567f5efc25ad3744aee +size 3571817 diff --git a/release-notes/images/1_29/linenumbers.png b/release-notes/images/1_29/linenumbers.png new file mode 100644 index 0000000000000000000000000000000000000000..502535a0ad80727dc7f4361f647777b13c7ff7ec Binary files /dev/null and b/release-notes/images/1_29/linenumbers.png differ diff --git a/release-notes/images/1_29/loaded-scripts-view.png b/release-notes/images/1_29/loaded-scripts-view.png new file mode 100644 index 0000000000000000000000000000000000000000..c0067d2fd1de20e8fc2971446ce7e2ababa876ee Binary files /dev/null and b/release-notes/images/1_29/loaded-scripts-view.png differ diff --git a/release-notes/images/1_29/modified-in-link.png b/release-notes/images/1_29/modified-in-link.png new file mode 100644 index 0000000000000000000000000000000000000000..ea6265d133021b353e5047ac8782c5da1399df9c Binary files /dev/null and b/release-notes/images/1_29/modified-in-link.png differ diff --git a/release-notes/images/1_29/mojave-dark.png b/release-notes/images/1_29/mojave-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..323573c922790917f3f33f9066ca99579c4380a6 --- /dev/null +++ b/release-notes/images/1_29/mojave-dark.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d9a51080466efca4e5e2239306917323c6dc85dac6431e6ecbd202947bbdc69d +size 249574 diff --git a/release-notes/images/1_29/move-panel.png b/release-notes/images/1_29/move-panel.png new file mode 100644 index 0000000000000000000000000000000000000000..65134fe52c8bb194393eb8ac5b17c3b933e883ca Binary files /dev/null and b/release-notes/images/1_29/move-panel.png differ diff --git a/release-notes/images/1_29/multi-repl.png b/release-notes/images/1_29/multi-repl.png new file mode 100644 index 0000000000000000000000000000000000000000..b4410f188e57ffb88d5b005a6539cfae87638d3b Binary files /dev/null and b/release-notes/images/1_29/multi-repl.png differ diff --git a/release-notes/images/1_29/multiline.gif b/release-notes/images/1_29/multiline.gif new file mode 100644 index 0000000000000000000000000000000000000000..e9b9f5a52b01a1ff79beb1bdc18e8c6a3d4fa0e1 --- /dev/null +++ b/release-notes/images/1_29/multiline.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ca9bc7782e70bfa379c8c46ea7d349064158e5ddaeabcee6b1b09af634466bce +size 1092050 diff --git a/release-notes/images/1_29/pcre2.jpg b/release-notes/images/1_29/pcre2.jpg new file mode 100644 index 0000000000000000000000000000000000000000..25233bba129aee89a9978fb1682908c25a630fb7 Binary files /dev/null and b/release-notes/images/1_29/pcre2.jpg differ diff --git a/release-notes/images/1_29/pipelines.png b/release-notes/images/1_29/pipelines.png new file mode 100644 index 0000000000000000000000000000000000000000..0cfaa394fe021135eabbb91f1bb176ef98f5441d Binary files /dev/null and b/release-notes/images/1_29/pipelines.png differ diff --git a/release-notes/images/1_29/references-view.gif b/release-notes/images/1_29/references-view.gif new file mode 100644 index 0000000000000000000000000000000000000000..965f9ade454f3b5d01a66f459e3d76a5df6a17fb --- /dev/null +++ b/release-notes/images/1_29/references-view.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5ae1023e52137f57eb6e20ac6df97d1f557db1b17db6d935d401e0221320dc71 +size 3901194 diff --git a/release-notes/images/1_29/release-highlights.png b/release-notes/images/1_29/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..2b4ef04981e3c6b193b93a55c8152bf9703e586e Binary files /dev/null and b/release-notes/images/1_29/release-highlights.png differ diff --git a/release-notes/images/1_29/stack-frames.gif b/release-notes/images/1_29/stack-frames.gif new file mode 100644 index 0000000000000000000000000000000000000000..05b12966b541900d66b2e431e9322432cc0e2597 Binary files /dev/null and b/release-notes/images/1_29/stack-frames.gif differ diff --git a/release-notes/images/1_29/structured-view.png b/release-notes/images/1_29/structured-view.png new file mode 100644 index 0000000000000000000000000000000000000000..0709d991c0cde25d41aa58d5e20dce0cb4ab6ab6 Binary files /dev/null and b/release-notes/images/1_29/structured-view.png differ diff --git a/release-notes/images/1_29/view-collapse-all.png b/release-notes/images/1_29/view-collapse-all.png new file mode 100644 index 0000000000000000000000000000000000000000..1b35ff1f3f0d33fc27401c0943153b47cfea963d Binary files /dev/null and b/release-notes/images/1_29/view-collapse-all.png differ diff --git a/release-notes/images/1_29/view-label-highlights.png b/release-notes/images/1_29/view-label-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..ce724cc7207c10334d4fa1a96ed95d65447767b9 Binary files /dev/null and b/release-notes/images/1_29/view-label-highlights.png differ diff --git a/release-notes/images/1_29/workbench-navigation.gif b/release-notes/images/1_29/workbench-navigation.gif new file mode 100644 index 0000000000000000000000000000000000000000..ae29952940d924178b06ee807558ce5a182cd33e --- /dev/null +++ b/release-notes/images/1_29/workbench-navigation.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:872de3ea0775fc18bdf31471b555edc1aa5285804170d0531dbf74b6047155b8 +size 1093902 diff --git a/release-notes/images/1_30/api-sighelp-context.gif b/release-notes/images/1_30/api-sighelp-context.gif new file mode 100644 index 0000000000000000000000000000000000000000..a816e908c8fcb9951515678703b2179709234b8d --- /dev/null +++ b/release-notes/images/1_30/api-sighelp-context.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6f2a61b317ea40d0a06b2efd7d117e7312db08fba9904847e447c5c91c876840 +size 105157 diff --git a/release-notes/images/1_30/custom-title-menu-linux.png b/release-notes/images/1_30/custom-title-menu-linux.png new file mode 100644 index 0000000000000000000000000000000000000000..e39228a6fd81ee7952eed15ddb733e5c576d3216 --- /dev/null +++ b/release-notes/images/1_30/custom-title-menu-linux.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:35cf330c3a5e09799008bc03464b21e6ea110aacd5a926298413f03fc993e670 +size 154859 diff --git a/release-notes/images/1_30/debug-from-process-explorer.gif b/release-notes/images/1_30/debug-from-process-explorer.gif new file mode 100644 index 0000000000000000000000000000000000000000..ccf7da96d2dbf3fee19dffe1d5c171c110a48922 --- /dev/null +++ b/release-notes/images/1_30/debug-from-process-explorer.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8d3c94eb94e99b411d242883db7740150284932a782ad0de2931abbf54d3aa50 +size 1664548 diff --git a/release-notes/images/1_30/downgrade-Extension.gif b/release-notes/images/1_30/downgrade-Extension.gif new file mode 100644 index 0000000000000000000000000000000000000000..98c66fa3b9a6a3822c887670a272977ec4099043 --- /dev/null +++ b/release-notes/images/1_30/downgrade-Extension.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0d432ddf5e843879e1ba5081a5555140f0fa7010acead82d5579cf721984bbb2 +size 616051 diff --git a/release-notes/images/1_30/exthost-slow-the-movie.gif b/release-notes/images/1_30/exthost-slow-the-movie.gif new file mode 100644 index 0000000000000000000000000000000000000000..42b753ea87907647e637908934ad3ff79666dd10 --- /dev/null +++ b/release-notes/images/1_30/exthost-slow-the-movie.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4564bf864642f7c6c0bac1b2cd064598d608b7740937db419e97e5377122d117 +size 9810105 diff --git a/release-notes/images/1_30/go-to-declaration.png b/release-notes/images/1_30/go-to-declaration.png new file mode 100644 index 0000000000000000000000000000000000000000..1f2dc29a78d2f9bf648c6c0c408aea761e8b7878 --- /dev/null +++ b/release-notes/images/1_30/go-to-declaration.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7436474c7d4165d0007f74d00c31a47bf2c9f8663ab769e2df46db2891e6408e +size 162387 diff --git a/release-notes/images/1_30/html-custom-tag-attribute.gif b/release-notes/images/1_30/html-custom-tag-attribute.gif new file mode 100644 index 0000000000000000000000000000000000000000..0d6c2f264a066b1c2d4f5c62acfa80c21fdfb5b7 --- /dev/null +++ b/release-notes/images/1_30/html-custom-tag-attribute.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:87bb230054afd813dbeb9e44fc21f610bbeca859dff67a5bbce64dabb24db64b +size 5454202 diff --git a/release-notes/images/1_30/http-proxy-support.png b/release-notes/images/1_30/http-proxy-support.png new file mode 100644 index 0000000000000000000000000000000000000000..00f9ebbdc9183e4f1c30b28bc6ec19c1fd587952 Binary files /dev/null and b/release-notes/images/1_30/http-proxy-support.png differ diff --git a/release-notes/images/1_30/input-example.gif b/release-notes/images/1_30/input-example.gif new file mode 100644 index 0000000000000000000000000000000000000000..9afb8b5609d131aad7d690fa1a3ba537e3c7e8f6 --- /dev/null +++ b/release-notes/images/1_30/input-example.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0425efbc73e53ea022f347ad26fea9faa2d984e56ad5bf4e25212688311396eb +size 797303 diff --git a/release-notes/images/1_30/menu-bar-overflow.png b/release-notes/images/1_30/menu-bar-overflow.png new file mode 100644 index 0000000000000000000000000000000000000000..894e8aa6da5385ed316174cd9645d162840472bb Binary files /dev/null and b/release-notes/images/1_30/menu-bar-overflow.png differ diff --git a/release-notes/images/1_30/multiline-input.png b/release-notes/images/1_30/multiline-input.png new file mode 100644 index 0000000000000000000000000000000000000000..77e7a00474099b04e10760a353dc722f6aa8f2ae Binary files /dev/null and b/release-notes/images/1_30/multiline-input.png differ diff --git a/release-notes/images/1_30/references-viewlet.png b/release-notes/images/1_30/references-viewlet.png new file mode 100644 index 0000000000000000000000000000000000000000..15f11977ca6d1a63d7cbc7bc3dce17553d971787 --- /dev/null +++ b/release-notes/images/1_30/references-viewlet.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:815518e658f0d48e84fa70350f2ea74edbb945bd3862975b773e7c3e367bb2f0 +size 156089 diff --git a/release-notes/images/1_30/release-highlights.png b/release-notes/images/1_30/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..4dfa6b1d34486739cc13f77f891ced7b4eeaf91b Binary files /dev/null and b/release-notes/images/1_30/release-highlights.png differ diff --git a/release-notes/images/1_30/scrolling-menus.gif b/release-notes/images/1_30/scrolling-menus.gif new file mode 100644 index 0000000000000000000000000000000000000000..15a59c7c85c774010aef2edf5e7607e47154da0f Binary files /dev/null and b/release-notes/images/1_30/scrolling-menus.gif differ diff --git a/release-notes/images/1_30/settings-actions.png b/release-notes/images/1_30/settings-actions.png new file mode 100644 index 0000000000000000000000000000000000000000..b2bd340e5532bf56912e4a05e9339329ed09958b --- /dev/null +++ b/release-notes/images/1_30/settings-actions.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0c305897bdd7b7e2b69a0f39008d84904c06da7e146207f0cb43f6e89e942f88 +size 100187 diff --git a/release-notes/images/1_30/treeitem-description.png b/release-notes/images/1_30/treeitem-description.png new file mode 100644 index 0000000000000000000000000000000000000000..9497bc81b458a9669a5b5a4d66f213a7c8bfccdb Binary files /dev/null and b/release-notes/images/1_30/treeitem-description.png differ diff --git a/release-notes/images/1_30/treeview-message.png b/release-notes/images/1_30/treeview-message.png new file mode 100644 index 0000000000000000000000000000000000000000..a97ed97b154d87464748f42aeb6f6f1501f65599 Binary files /dev/null and b/release-notes/images/1_30/treeview-message.png differ diff --git a/release-notes/images/1_30/ts-import-icons.png b/release-notes/images/1_30/ts-import-icons.png new file mode 100644 index 0000000000000000000000000000000000000000..bfd81eef13270b1c50cab81ed10f82320b704462 Binary files /dev/null and b/release-notes/images/1_30/ts-import-icons.png differ diff --git a/release-notes/images/1_30/ts-markdown-jsdocs.png b/release-notes/images/1_30/ts-markdown-jsdocs.png new file mode 100644 index 0000000000000000000000000000000000000000..02ea7290ef4156eba47f9a0fb3d7b560b79ebf26 Binary files /dev/null and b/release-notes/images/1_30/ts-markdown-jsdocs.png differ diff --git a/release-notes/images/1_30/ts-new-callback-nav.png b/release-notes/images/1_30/ts-new-callback-nav.png new file mode 100644 index 0000000000000000000000000000000000000000..998d73fc89321077ea15c6e0398b0d6ec369389f --- /dev/null +++ b/release-notes/images/1_30/ts-new-callback-nav.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3011b211c09690aaed240ef62d8785c3360b0ade534b2ccd801726439fca3587 +size 140274 diff --git a/release-notes/images/1_30/ts-new-quickfix.gif b/release-notes/images/1_30/ts-new-quickfix.gif new file mode 100644 index 0000000000000000000000000000000000000000..1b98457b9b8ad8d467039963b89600e9ca178cf7 --- /dev/null +++ b/release-notes/images/1_30/ts-new-quickfix.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b7242d1d631e5febb2fd9eed384c7586e170f38d7a5af48cca9327b2bd1e2756 +size 1488733 diff --git a/release-notes/images/1_30/ts-old-callback-nav.png b/release-notes/images/1_30/ts-old-callback-nav.png new file mode 100644 index 0000000000000000000000000000000000000000..03090952012b2d871ebb3f58e863ba7436478d5a --- /dev/null +++ b/release-notes/images/1_30/ts-old-callback-nav.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fddfd56bb7ad2c57715ba0802642245600757daa413f1897f7d0f6e1f11a7f32 +size 134539 diff --git a/release-notes/images/1_30/ts-rename.gif b/release-notes/images/1_30/ts-rename.gif new file mode 100644 index 0000000000000000000000000000000000000000..971b770bff0cda62bbc536af024e4c36589e8c15 --- /dev/null +++ b/release-notes/images/1_30/ts-rename.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4e1fb468ec66799ad8bc95afd26c606f41dba1d17d5dfc187fa6c72af5fb1d92 +size 2805373 diff --git a/release-notes/images/1_31/api-preferred-after.png b/release-notes/images/1_31/api-preferred-after.png new file mode 100644 index 0000000000000000000000000000000000000000..02363a5f33e1cea51ea83e669e43e1a201c57b23 Binary files /dev/null and b/release-notes/images/1_31/api-preferred-after.png differ diff --git a/release-notes/images/1_31/api-preferred.png b/release-notes/images/1_31/api-preferred.png new file mode 100644 index 0000000000000000000000000000000000000000..01b99215392a05a50d47bfb0333b9121a4417e5f Binary files /dev/null and b/release-notes/images/1_31/api-preferred.png differ diff --git a/release-notes/images/1_31/api-toc.png b/release-notes/images/1_31/api-toc.png new file mode 100644 index 0000000000000000000000000000000000000000..1054d88461cde90f7d489f11d3fc902c58f6db52 --- /dev/null +++ b/release-notes/images/1_31/api-toc.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:30bc45bb9e89c87d2fb20ed3ff3a8cebe2084f9d91e82447f4fe5ae17b0af391 +size 170804 diff --git a/release-notes/images/1_31/customdata.gif b/release-notes/images/1_31/customdata.gif new file mode 100644 index 0000000000000000000000000000000000000000..a7e9279af5d3faf42af91f086ae44105d8580813 --- /dev/null +++ b/release-notes/images/1_31/customdata.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a3dfc4d062e9435c03da072d62ce9640e48041ccb2d97a2bbdebbb788b3763bd +size 1793684 diff --git a/release-notes/images/1_31/cut.png b/release-notes/images/1_31/cut.png new file mode 100644 index 0000000000000000000000000000000000000000..49089eb6fef0c7a0a113fb605cdf3fd4baec7d84 Binary files /dev/null and b/release-notes/images/1_31/cut.png differ diff --git a/release-notes/images/1_31/go-menu.png b/release-notes/images/1_31/go-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..38f1704a7096b431e829a08e21cb77baf2e41e23 Binary files /dev/null and b/release-notes/images/1_31/go-menu.png differ diff --git a/release-notes/images/1_31/html-css-json-selection.gif b/release-notes/images/1_31/html-css-json-selection.gif new file mode 100644 index 0000000000000000000000000000000000000000..9e782961c243e6a2c81b7acc9183a01dd0d6f351 --- /dev/null +++ b/release-notes/images/1_31/html-css-json-selection.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:10ca28d7ed4de61e7d592979a003b9e573d3ac6c7b324bae70f5754356e017f5 +size 1501668 diff --git a/release-notes/images/1_31/http-proxy-support.png b/release-notes/images/1_31/http-proxy-support.png new file mode 100644 index 0000000000000000000000000000000000000000..e71b0a53087391192f548c5e3040ca60983d1da2 Binary files /dev/null and b/release-notes/images/1_31/http-proxy-support.png differ diff --git a/release-notes/images/1_31/live-theme-editing.gif b/release-notes/images/1_31/live-theme-editing.gif new file mode 100644 index 0000000000000000000000000000000000000000..2f6adea4fef0b85fd925c79a656094995b0d5eb3 --- /dev/null +++ b/release-notes/images/1_31/live-theme-editing.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9ff52c706860de3375e43b493ca5e2f4454d48c28b4f70e9be5b413116dacf31 +size 182563 diff --git a/release-notes/images/1_31/no-reload-language-extension.gif b/release-notes/images/1_31/no-reload-language-extension.gif new file mode 100644 index 0000000000000000000000000000000000000000..d75b0b5da3f98cc41f18a1b3d0f503c32cefb9e5 --- /dev/null +++ b/release-notes/images/1_31/no-reload-language-extension.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a32db35d57e9475b518f682e6dfddd605b9616b3352417cf54d329cd06f75971 +size 1909117 diff --git a/release-notes/images/1_31/octicons-updates.png b/release-notes/images/1_31/octicons-updates.png new file mode 100644 index 0000000000000000000000000000000000000000..e9a22ec977aef43f052700db7cf6f10d9da1ece3 Binary files /dev/null and b/release-notes/images/1_31/octicons-updates.png differ diff --git a/release-notes/images/1_31/panel-only.png b/release-notes/images/1_31/panel-only.png new file mode 100644 index 0000000000000000000000000000000000000000..b2cc649c68ce51f18d2ba58266045ae2166dcfd8 Binary files /dev/null and b/release-notes/images/1_31/panel-only.png differ diff --git a/release-notes/images/1_31/problems-multi-line.gif b/release-notes/images/1_31/problems-multi-line.gif new file mode 100644 index 0000000000000000000000000000000000000000..698cd8147961ec5feb8d206d79d9dcfe706d15a5 --- /dev/null +++ b/release-notes/images/1_31/problems-multi-line.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5a7703e689252da25bb8d8a8b1dbeb25b664f9148e41505715ea7afca1643a89 +size 4636138 diff --git a/release-notes/images/1_31/ref-history.png b/release-notes/images/1_31/ref-history.png new file mode 100644 index 0000000000000000000000000000000000000000..9b2d360d5d7a4f68531b66da6ec74251794afe06 --- /dev/null +++ b/release-notes/images/1_31/ref-history.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6bee0e7d823816a2714f50825971aa64e7b457a29d5e399ae59637868343d111 +size 191650 diff --git a/release-notes/images/1_31/release-highlights.png b/release-notes/images/1_31/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..5ae3a6286aab00b131471c397354a669c1773cf4 Binary files /dev/null and b/release-notes/images/1_31/release-highlights.png differ diff --git a/release-notes/images/1_31/screencast.gif b/release-notes/images/1_31/screencast.gif new file mode 100644 index 0000000000000000000000000000000000000000..4aa1ecabe44aad7c420231c8bc96c72f2aa019af --- /dev/null +++ b/release-notes/images/1_31/screencast.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9eccf3ce3b079ca592140a521bb57e348e88090759a27127a167ffd0cdb76780 +size 3194729 diff --git a/release-notes/images/1_31/select-all.gif b/release-notes/images/1_31/select-all.gif new file mode 100644 index 0000000000000000000000000000000000000000..bc14161a07984c333312efbed990dbfe0b847b6a --- /dev/null +++ b/release-notes/images/1_31/select-all.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:22eb67e9468be57a0d11b7b20cbc0efc400dac037e7532cc252a2cb7e0dd283c +size 233184 diff --git a/release-notes/images/1_31/sideBySideTasks.png b/release-notes/images/1_31/sideBySideTasks.png new file mode 100644 index 0000000000000000000000000000000000000000..7c062f308f19cdf51aeba94e9499710f7c6e0ad4 Binary files /dev/null and b/release-notes/images/1_31/sideBySideTasks.png differ diff --git a/release-notes/images/1_31/smart-select-demo.gif b/release-notes/images/1_31/smart-select-demo.gif new file mode 100644 index 0000000000000000000000000000000000000000..4661f12837f77fcee251ce0fac3084e62806b377 --- /dev/null +++ b/release-notes/images/1_31/smart-select-demo.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c03d9f0c7c6a4ca284d132cde0ea3d6a95e5c3c720270ff2001562dc4d0310fb +size 640387 diff --git a/release-notes/images/1_31/stylus-completion.png b/release-notes/images/1_31/stylus-completion.png new file mode 100644 index 0000000000000000000000000000000000000000..a6c98fe99943418a3375084a8bb55422a860aea5 Binary files /dev/null and b/release-notes/images/1_31/stylus-completion.png differ diff --git a/release-notes/images/1_31/terminal-conpty-after.png b/release-notes/images/1_31/terminal-conpty-after.png new file mode 100644 index 0000000000000000000000000000000000000000..39c932c9079542060c64c28fd0d9ae0ccf70eeb8 Binary files /dev/null and b/release-notes/images/1_31/terminal-conpty-after.png differ diff --git a/release-notes/images/1_31/terminal-conpty-before.png b/release-notes/images/1_31/terminal-conpty-before.png new file mode 100644 index 0000000000000000000000000000000000000000..fc9883b4672734e67cbad52a17bacdda8ab57394 Binary files /dev/null and b/release-notes/images/1_31/terminal-conpty-before.png differ diff --git a/release-notes/images/1_31/terminal-cwd-links.gif b/release-notes/images/1_31/terminal-cwd-links.gif new file mode 100644 index 0000000000000000000000000000000000000000..46288fe3f96dced4f38a40866ef2e163a38bd49a --- /dev/null +++ b/release-notes/images/1_31/terminal-cwd-links.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2cd7e1e8a1414139daffa12c52f52ec3cf67bb3e0095c5d1d1a463fb4967f282 +size 992980 diff --git a/release-notes/images/1_31/terminal-reflow.gif b/release-notes/images/1_31/terminal-reflow.gif new file mode 100644 index 0000000000000000000000000000000000000000..d1c259a8638d431ccbeabaa7de8a6348e862fe73 --- /dev/null +++ b/release-notes/images/1_31/terminal-reflow.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f530043fa3a642e9c2873f00063bde99560a751dd824686fbc258dff02cc0502 +size 877653 diff --git a/release-notes/images/1_31/type-filter.gif b/release-notes/images/1_31/type-filter.gif new file mode 100644 index 0000000000000000000000000000000000000000..4d396a2673621c2b28ff0409e7b8e5dbdbf93c29 --- /dev/null +++ b/release-notes/images/1_31/type-filter.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6746bc8f073bd6b9cbfb11ce7fef1fb7c6a11d647e21df48be21fcec8397001e +size 630829 diff --git a/release-notes/images/1_32/autofix-ligthbulb.png b/release-notes/images/1_32/autofix-ligthbulb.png new file mode 100644 index 0000000000000000000000000000000000000000..aba4ef0cb084ae53455b38bac6ead48401437823 Binary files /dev/null and b/release-notes/images/1_32/autofix-ligthbulb.png differ diff --git a/release-notes/images/1_32/column-selection-alt-key.gif b/release-notes/images/1_32/column-selection-alt-key.gif new file mode 100644 index 0000000000000000000000000000000000000000..3edfe48f209c1fc373b4a0f454a0ca3e90e05ce8 --- /dev/null +++ b/release-notes/images/1_32/column-selection-alt-key.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:df9c85bb3ea17bba94e94e74aeaf322a2115c454f5a654bb86516c26065f9233 +size 1232450 diff --git a/release-notes/images/1_32/debug-console-font.gif b/release-notes/images/1_32/debug-console-font.gif new file mode 100644 index 0000000000000000000000000000000000000000..d6fd5aec28f9e31454520a88ff9d52ff24c29701 --- /dev/null +++ b/release-notes/images/1_32/debug-console-font.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f4141c93f5c5aec1fb2a5fc204a413ef230a33fe5bc08cf0b0ab4fb5bbc0317e +size 685867 diff --git a/release-notes/images/1_32/debug-console-wrap.png b/release-notes/images/1_32/debug-console-wrap.png new file mode 100644 index 0000000000000000000000000000000000000000..078651a2e23ba3bf27bff97158e711e43f73902f Binary files /dev/null and b/release-notes/images/1_32/debug-console-wrap.png differ diff --git a/release-notes/images/1_32/debug-toolbar.png b/release-notes/images/1_32/debug-toolbar.png new file mode 100644 index 0000000000000000000000000000000000000000..7200906a71c6683e9b298d2df039290a7ba6b3a3 Binary files /dev/null and b/release-notes/images/1_32/debug-toolbar.png differ diff --git a/release-notes/images/1_32/hover.png b/release-notes/images/1_32/hover.png new file mode 100644 index 0000000000000000000000000000000000000000..618d7c212da9619c5289a35632034ec266eedc6f Binary files /dev/null and b/release-notes/images/1_32/hover.png differ diff --git a/release-notes/images/1_32/html-attribute-completion.gif b/release-notes/images/1_32/html-attribute-completion.gif new file mode 100644 index 0000000000000000000000000000000000000000..06a91a1bfb91acb049ba5cec38094f6b22f7d58d --- /dev/null +++ b/release-notes/images/1_32/html-attribute-completion.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8151d2b89fc0bacdd8fd811150cd99b06f33b8f1bc36c365295fb0780d37e5a4 +size 2047828 diff --git a/release-notes/images/1_32/keyboard-shortcuts-when.gif b/release-notes/images/1_32/keyboard-shortcuts-when.gif new file mode 100644 index 0000000000000000000000000000000000000000..2f7a0522489afc6a7b36fcaa7e12c20b89c9b4ae --- /dev/null +++ b/release-notes/images/1_32/keyboard-shortcuts-when.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3f9baea22f2aba41695eb27126c7c8ac05a92af7104eb8e99df868afc8a1c484 +size 1710448 diff --git a/release-notes/images/1_32/problem-hover.png b/release-notes/images/1_32/problem-hover.png new file mode 100644 index 0000000000000000000000000000000000000000..c0eb91ef250934861157894d38003d6e6d05a0a1 --- /dev/null +++ b/release-notes/images/1_32/problem-hover.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:722077560ecf4613d40678e4a40001325c5f6bd73ee312a8ad3308073173032f +size 312849 diff --git a/release-notes/images/1_32/problem-peek.png b/release-notes/images/1_32/problem-peek.png new file mode 100644 index 0000000000000000000000000000000000000000..7d0d3d663789307f760697fba18cc71333375577 Binary files /dev/null and b/release-notes/images/1_32/problem-peek.png differ diff --git a/release-notes/images/1_32/release-highlights.png b/release-notes/images/1_32/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..a3647f4ed69453f055ba3bb2a897b6fb8f60ffa2 Binary files /dev/null and b/release-notes/images/1_32/release-highlights.png differ diff --git a/release-notes/images/1_32/server-ready.gif b/release-notes/images/1_32/server-ready.gif new file mode 100644 index 0000000000000000000000000000000000000000..d9431095984fe16898a079c9f5126d407d9d12f2 --- /dev/null +++ b/release-notes/images/1_32/server-ready.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2a77ed5bfa7e6d71ef0a6e5df452889d9ca35c78ce53639b8144539bdc3a84f8 +size 3374417 diff --git a/release-notes/images/1_32/theme-install.gif b/release-notes/images/1_32/theme-install.gif new file mode 100644 index 0000000000000000000000000000000000000000..a5552722457d319a49456e660cd924f9854e4e53 --- /dev/null +++ b/release-notes/images/1_32/theme-install.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a5f5af9f6eca838db48693551230f1bac7427abb6d2c1a2962091ed5d484a876 +size 2080436 diff --git a/release-notes/images/1_32/vetur-intellisense-vue-template.gif b/release-notes/images/1_32/vetur-intellisense-vue-template.gif new file mode 100644 index 0000000000000000000000000000000000000000..30a95e501d88b1dc14ce7830269159794d3b523d --- /dev/null +++ b/release-notes/images/1_32/vetur-intellisense-vue-template.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:04e5fec43897be576a4c4b8e205ce678d7c54786a2c765fbd6ad5c46560b4b1e +size 5424470 diff --git a/release-notes/images/1_32/webpack-logo.png b/release-notes/images/1_32/webpack-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..9d5af42d719c263729ac088ea9db357adaea2d71 Binary files /dev/null and b/release-notes/images/1_32/webpack-logo.png differ diff --git a/release-notes/images/1_5/Minimal.png b/release-notes/images/1_5/Minimal.png new file mode 100644 index 0000000000000000000000000000000000000000..20803fc7db02b36fd3722148e9dce30d43842e47 Binary files /dev/null and b/release-notes/images/1_5/Minimal.png differ diff --git a/release-notes/images/1_5/None.png b/release-notes/images/1_5/None.png new file mode 100644 index 0000000000000000000000000000000000000000..1a2bbb327fc94b99d7e262e224214d03d76904ae Binary files /dev/null and b/release-notes/images/1_5/None.png differ diff --git a/release-notes/images/1_5/Seti.png b/release-notes/images/1_5/Seti.png new file mode 100644 index 0000000000000000000000000000000000000000..7b4b6e1c85afb4108021529e37cb71638d2a64f3 Binary files /dev/null and b/release-notes/images/1_5/Seti.png differ diff --git a/release-notes/images/1_5/debug-console-attribute.png b/release-notes/images/1_5/debug-console-attribute.png new file mode 100644 index 0000000000000000000000000000000000000000..5273a3baf82d9e0ca5cf583c8d0d83680a3b7053 Binary files /dev/null and b/release-notes/images/1_5/debug-console-attribute.png differ diff --git a/release-notes/images/1_5/debug_repl_multiline.png b/release-notes/images/1_5/debug_repl_multiline.png new file mode 100644 index 0000000000000000000000000000000000000000..bcdc96c5f9021b7c61e3cd28c3f06a59a9be0253 Binary files /dev/null and b/release-notes/images/1_5/debug_repl_multiline.png differ diff --git a/release-notes/images/1_5/debug_repl_suggest.png b/release-notes/images/1_5/debug_repl_suggest.png new file mode 100644 index 0000000000000000000000000000000000000000..32fd1771dcd7181ef419248c4de06da1cbbe2287 Binary files /dev/null and b/release-notes/images/1_5/debug_repl_suggest.png differ diff --git a/release-notes/images/1_5/debug_variable_paging.png b/release-notes/images/1_5/debug_variable_paging.png new file mode 100644 index 0000000000000000000000000000000000000000..a85213a4377a6f405f7d63d64f66a375d808f088 Binary files /dev/null and b/release-notes/images/1_5/debug_variable_paging.png differ diff --git a/release-notes/images/1_5/extension-details.png b/release-notes/images/1_5/extension-details.png new file mode 100644 index 0000000000000000000000000000000000000000..f203e43a3524731dc5daef89b0097277ec43d51f Binary files /dev/null and b/release-notes/images/1_5/extension-details.png differ diff --git a/release-notes/images/1_5/extension-sort.png b/release-notes/images/1_5/extension-sort.png new file mode 100644 index 0000000000000000000000000000000000000000..e0e2b70f91faa3fbdbb6d45a199b1f685f0a46bc Binary files /dev/null and b/release-notes/images/1_5/extension-sort.png differ diff --git a/release-notes/images/1_5/extension-update-all.png b/release-notes/images/1_5/extension-update-all.png new file mode 100644 index 0000000000000000000000000000000000000000..1f3e8bc6e11079680f19617844e909e7f3ef7510 Binary files /dev/null and b/release-notes/images/1_5/extension-update-all.png differ diff --git a/release-notes/images/1_5/social.jpg b/release-notes/images/1_5/social.jpg new file mode 100644 index 0000000000000000000000000000000000000000..ea4061fe26b6b403dfd726e63c4b37389f492e22 Binary files /dev/null and b/release-notes/images/1_5/social.jpg differ diff --git a/release-notes/images/1_5/ts-version-check.png b/release-notes/images/1_5/ts-version-check.png new file mode 100644 index 0000000000000000000000000000000000000000..76d67f62848c8f8b13e22bc7dca9fece0b0ce290 Binary files /dev/null and b/release-notes/images/1_5/ts-version-check.png differ diff --git a/release-notes/images/1_6/builtin.png b/release-notes/images/1_6/builtin.png new file mode 100644 index 0000000000000000000000000000000000000000..292628ef00389d8734fb1a4514d91f916e207a94 Binary files /dev/null and b/release-notes/images/1_6/builtin.png differ diff --git a/release-notes/images/1_6/corrupt-install.png b/release-notes/images/1_6/corrupt-install.png new file mode 100644 index 0000000000000000000000000000000000000000..4a3ae091b791d12a161643ef21556fd0e2e2198d Binary files /dev/null and b/release-notes/images/1_6/corrupt-install.png differ diff --git a/release-notes/images/1_6/dirty.png b/release-notes/images/1_6/dirty.png new file mode 100644 index 0000000000000000000000000000000000000000..16ad1954cd89a142a97d0be320403c403d75e873 Binary files /dev/null and b/release-notes/images/1_6/dirty.png differ diff --git a/release-notes/images/1_6/extension-identifier.png b/release-notes/images/1_6/extension-identifier.png new file mode 100644 index 0000000000000000000000000000000000000000..5f40a58d9d158d734ad4c321a4b73901c35d86b9 Binary files /dev/null and b/release-notes/images/1_6/extension-identifier.png differ diff --git a/release-notes/images/1_6/hover.png b/release-notes/images/1_6/hover.png new file mode 100644 index 0000000000000000000000000000000000000000..4dd3a6b2af106fa0267bcee16a29b9c3b28a6547 Binary files /dev/null and b/release-notes/images/1_6/hover.png differ diff --git a/release-notes/images/1_6/icons.png b/release-notes/images/1_6/icons.png new file mode 100644 index 0000000000000000000000000000000000000000..42c1d3c1a1c30f47c0bdbb68f11e794891249358 Binary files /dev/null and b/release-notes/images/1_6/icons.png differ diff --git a/release-notes/images/1_6/recommendations.png b/release-notes/images/1_6/recommendations.png new file mode 100644 index 0000000000000000000000000000000000000000..d5ac8fd64b1a7aad758792698e1fdbfbcd83dfd3 Binary files /dev/null and b/release-notes/images/1_6/recommendations.png differ diff --git a/release-notes/images/1_6/release-highlights.png b/release-notes/images/1_6/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..4073b2fdbadb671df6d268bd7d616e668b177f1c Binary files /dev/null and b/release-notes/images/1_6/release-highlights.png differ diff --git a/release-notes/images/1_6/status.png b/release-notes/images/1_6/status.png new file mode 100644 index 0000000000000000000000000000000000000000..1aa37e796637f64706e1e1118f6e4c4f372cd33c Binary files /dev/null and b/release-notes/images/1_6/status.png differ diff --git a/release-notes/images/1_6/switch-window-animation.gif b/release-notes/images/1_6/switch-window-animation.gif new file mode 100644 index 0000000000000000000000000000000000000000..45be1f89056fe324f498f7b39385e118f16d1409 Binary files /dev/null and b/release-notes/images/1_6/switch-window-animation.gif differ diff --git a/release-notes/images/1_7/css-intellisense-in-html.png b/release-notes/images/1_7/css-intellisense-in-html.png new file mode 100644 index 0000000000000000000000000000000000000000..b0efd4f56c03a5f4138c91d02d31c10b56edce74 Binary files /dev/null and b/release-notes/images/1_7/css-intellisense-in-html.png differ diff --git a/release-notes/images/1_7/disableAll.png b/release-notes/images/1_7/disableAll.png new file mode 100644 index 0000000000000000000000000000000000000000..12c3cec341a9827519b331daba82e4c1b474cbaf Binary files /dev/null and b/release-notes/images/1_7/disableAll.png differ diff --git a/release-notes/images/1_7/disableExtension.png b/release-notes/images/1_7/disableExtension.png new file mode 100644 index 0000000000000000000000000000000000000000..6e6e511e921ae5f8f11c5c046c560f058bfe5fca Binary files /dev/null and b/release-notes/images/1_7/disableExtension.png differ diff --git a/release-notes/images/1_7/extensionPack.png b/release-notes/images/1_7/extensionPack.png new file mode 100644 index 0000000000000000000000000000000000000000..a0c87e1dcfe5d19a52bed0f7c4a6f1ea0d86a55e Binary files /dev/null and b/release-notes/images/1_7/extensionPack.png differ diff --git a/release-notes/images/1_7/format-context-menu.png b/release-notes/images/1_7/format-context-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..6bd47d0217bd0c228d0ac99e028a605a6872f77c Binary files /dev/null and b/release-notes/images/1_7/format-context-menu.png differ diff --git a/release-notes/images/1_7/hitCount.gif b/release-notes/images/1_7/hitCount.gif new file mode 100644 index 0000000000000000000000000000000000000000..bd048504ffe5f2ebefc2ab55fce30717f7765583 --- /dev/null +++ b/release-notes/images/1_7/hitCount.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6b4d63d019b23acdaa93936553043fb212c909c490c4ae6d934fed796483792a +size 217290 diff --git a/release-notes/images/1_7/horizontal.png b/release-notes/images/1_7/horizontal.png new file mode 100644 index 0000000000000000000000000000000000000000..a13470cd7f7eb11769904e6eca3f2546f119259c --- /dev/null +++ b/release-notes/images/1_7/horizontal.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cbcac21cbcef71668467e57082eb2851299477936a01ad6d3415f0bf6ce1c16d +size 293584 diff --git a/release-notes/images/1_7/keyboard-shortcuts-pdf.png b/release-notes/images/1_7/keyboard-shortcuts-pdf.png new file mode 100644 index 0000000000000000000000000000000000000000..a2bd6c6deed5b4f24ea188c5c5689af06aac87c4 Binary files /dev/null and b/release-notes/images/1_7/keyboard-shortcuts-pdf.png differ diff --git a/release-notes/images/1_7/keymaps.png b/release-notes/images/1_7/keymaps.png new file mode 100644 index 0000000000000000000000000000000000000000..e1bf56257115738b61aadfbfb76c41d34f286a25 Binary files /dev/null and b/release-notes/images/1_7/keymaps.png differ diff --git a/release-notes/images/1_7/launchjson.png b/release-notes/images/1_7/launchjson.png new file mode 100644 index 0000000000000000000000000000000000000000..1926294e3ef6cf59bbd70dfa6fd3a2a9df3b1922 Binary files /dev/null and b/release-notes/images/1_7/launchjson.png differ diff --git a/release-notes/images/1_7/marketplace-formatters.png b/release-notes/images/1_7/marketplace-formatters.png new file mode 100644 index 0000000000000000000000000000000000000000..355ea0195943068fb079e3df6a521520d9bfc0f7 Binary files /dev/null and b/release-notes/images/1_7/marketplace-formatters.png differ diff --git a/release-notes/images/1_7/multiDebug.gif b/release-notes/images/1_7/multiDebug.gif new file mode 100644 index 0000000000000000000000000000000000000000..3d1ad70d3058331aebf813e300ead0d5829a49ca --- /dev/null +++ b/release-notes/images/1_7/multiDebug.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:93395ef0e3dc30b84a81d2d7812b1405a10b87e84f8bb391e0496b230d70bd77 +size 1236929 diff --git a/release-notes/images/1_7/release-highlights.png b/release-notes/images/1_7/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..149c511eee8390b3458ccc8aedd1e275e4c00685 Binary files /dev/null and b/release-notes/images/1_7/release-highlights.png differ diff --git a/release-notes/images/1_7/toggle-horizontal-layout.png b/release-notes/images/1_7/toggle-horizontal-layout.png new file mode 100644 index 0000000000000000000000000000000000000000..0a1a772ed21eed2636893f18b4e6e0d94e7cf09b Binary files /dev/null and b/release-notes/images/1_7/toggle-horizontal-layout.png differ diff --git a/release-notes/images/1_8/add-config.gif b/release-notes/images/1_8/add-config.gif new file mode 100644 index 0000000000000000000000000000000000000000..325f514b2dcff705f1e43785446600ecd13132cf --- /dev/null +++ b/release-notes/images/1_8/add-config.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2e11d0563095d857b60027c37d7bbd03f71f8e91c690c0bbee85b2a16c11f006 +size 124613 diff --git a/release-notes/images/1_8/breakpoints.png b/release-notes/images/1_8/breakpoints.png new file mode 100644 index 0000000000000000000000000000000000000000..35aa4efffab5c4658da9a4e57eb3acffe8b8e925 Binary files /dev/null and b/release-notes/images/1_8/breakpoints.png differ diff --git a/release-notes/images/1_8/css-in-html.png b/release-notes/images/1_8/css-in-html.png new file mode 100644 index 0000000000000000000000000000000000000000..e7190068fec9a71c907124de506cd509ba9cc8c6 Binary files /dev/null and b/release-notes/images/1_8/css-in-html.png differ diff --git a/release-notes/images/1_8/debug-actions-widget.png b/release-notes/images/1_8/debug-actions-widget.png new file mode 100644 index 0000000000000000000000000000000000000000..09033971bb3631f0dcbde1b9e394c6a9563b48b6 Binary files /dev/null and b/release-notes/images/1_8/debug-actions-widget.png differ diff --git a/release-notes/images/1_8/debug-callstack.png b/release-notes/images/1_8/debug-callstack.png new file mode 100644 index 0000000000000000000000000000000000000000..bb70825ed80c39d9d833f8951c00ee163c549ce9 Binary files /dev/null and b/release-notes/images/1_8/debug-callstack.png differ diff --git a/release-notes/images/1_8/debug-start.png b/release-notes/images/1_8/debug-start.png new file mode 100644 index 0000000000000000000000000000000000000000..d879cb99ee3bbfacc2b087cc928bc9ae6b379fb4 Binary files /dev/null and b/release-notes/images/1_8/debug-start.png differ diff --git a/release-notes/images/1_8/diff-indicators.png b/release-notes/images/1_8/diff-indicators.png new file mode 100644 index 0000000000000000000000000000000000000000..9557ec8e2c96475c61c2f01ccc0d4460977b32c6 Binary files /dev/null and b/release-notes/images/1_8/diff-indicators.png differ diff --git a/release-notes/images/1_8/hide-activitybar.gif b/release-notes/images/1_8/hide-activitybar.gif new file mode 100644 index 0000000000000000000000000000000000000000..9264c010d293d6e3979563812f97859307fd2316 --- /dev/null +++ b/release-notes/images/1_8/hide-activitybar.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0c1864cc711446ed7b88932cf4696c5d5c9f0011aa0ee80b3205dcc57a89fb72 +size 163471 diff --git a/release-notes/images/1_8/javascript-in-html.gif b/release-notes/images/1_8/javascript-in-html.gif new file mode 100644 index 0000000000000000000000000000000000000000..a66b2c22f3debefd6e666745763d90a3fb7290a7 --- /dev/null +++ b/release-notes/images/1_8/javascript-in-html.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:93453be1d0dc10be9d18fa034591384da4105e309bb1b9556a3717307e062c43 +size 1250535 diff --git a/release-notes/images/1_8/overflow.png b/release-notes/images/1_8/overflow.png new file mode 100644 index 0000000000000000000000000000000000000000..f7c3716aad63cfd29082787c91d8786950d14734 Binary files /dev/null and b/release-notes/images/1_8/overflow.png differ diff --git a/release-notes/images/1_8/quick-edit-settings.gif b/release-notes/images/1_8/quick-edit-settings.gif new file mode 100644 index 0000000000000000000000000000000000000000..f3739a08485669b73b5a6507c56c3980c90f5f4f --- /dev/null +++ b/release-notes/images/1_8/quick-edit-settings.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:202dacb0bbd163ba36385b1cf063a75ba77bbacd56f1044c875c0136c7cec2e2 +size 4242799 diff --git a/release-notes/images/1_8/recommended-keymap-extensions.png b/release-notes/images/1_8/recommended-keymap-extensions.png new file mode 100644 index 0000000000000000000000000000000000000000..7cf84f4f300c082ae076d6dbb5f884be76c462d6 Binary files /dev/null and b/release-notes/images/1_8/recommended-keymap-extensions.png differ diff --git a/release-notes/images/1_8/release-highlights.png b/release-notes/images/1_8/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..9ac9b72609140669369d89154856c68962785f8e Binary files /dev/null and b/release-notes/images/1_8/release-highlights.png differ diff --git a/release-notes/images/1_8/render-line-highlight.png b/release-notes/images/1_8/render-line-highlight.png new file mode 100644 index 0000000000000000000000000000000000000000..437301f0a37d2e2f368ff7e2ff983eaf41a7ea04 Binary files /dev/null and b/release-notes/images/1_8/render-line-highlight.png differ diff --git a/release-notes/images/1_8/reverse-continue.png b/release-notes/images/1_8/reverse-continue.png new file mode 100644 index 0000000000000000000000000000000000000000..02184ed9f39d4d2e04f9b89a561ed537b9dfb5f5 Binary files /dev/null and b/release-notes/images/1_8/reverse-continue.png differ diff --git a/release-notes/images/1_8/search-settings.gif b/release-notes/images/1_8/search-settings.gif new file mode 100644 index 0000000000000000000000000000000000000000..7e0b2e639436f7bc4f03d3773e29530e52156db6 --- /dev/null +++ b/release-notes/images/1_8/search-settings.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f70697f61eb89fa7c2f66180a824fd1261fbf8d29e318a5e090e5b00de1970cc +size 2555435 diff --git a/release-notes/images/1_8/selection-menu.png b/release-notes/images/1_8/selection-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..20d55d652ce539c57d61acbf804475c48ce03e15 Binary files /dev/null and b/release-notes/images/1_8/selection-menu.png differ diff --git a/release-notes/images/1_8/settings-groups.png b/release-notes/images/1_8/settings-groups.png new file mode 100644 index 0000000000000000000000000000000000000000..6723c2edb70cf48356c96402171b1b079d958d9c Binary files /dev/null and b/release-notes/images/1_8/settings-groups.png differ diff --git a/release-notes/images/1_8/view-picker.png b/release-notes/images/1_8/view-picker.png new file mode 100644 index 0000000000000000000000000000000000000000..2b62103afb8d5e970f19f6cb14204b1715316287 Binary files /dev/null and b/release-notes/images/1_8/view-picker.png differ diff --git a/release-notes/images/1_8/viewlet.gif b/release-notes/images/1_8/viewlet.gif new file mode 100644 index 0000000000000000000000000000000000000000..1d81ec915790a1664bd3fd193c916681f62f8626 --- /dev/null +++ b/release-notes/images/1_8/viewlet.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ca70616af24ea6da1a58ca763788ff2316dcc36c416710a4525e1537d795b599 +size 439977 diff --git a/release-notes/images/1_9/add_launch.png b/release-notes/images/1_9/add_launch.png new file mode 100644 index 0000000000000000000000000000000000000000..6de9e71e1cf72389b784612f6e9f1ba4ad36634d Binary files /dev/null and b/release-notes/images/1_9/add_launch.png differ diff --git a/release-notes/images/1_9/closeall.png b/release-notes/images/1_9/closeall.png new file mode 100644 index 0000000000000000000000000000000000000000..abfad5c4a7a56d667f5f7e4a9137e1ee6073b5b4 Binary files /dev/null and b/release-notes/images/1_9/closeall.png differ diff --git a/release-notes/images/1_9/configure-lang-mode.png b/release-notes/images/1_9/configure-lang-mode.png new file mode 100644 index 0000000000000000000000000000000000000000..8f8e4e47b5c12bfb1d292dc7fad8c51c56ef1e8e --- /dev/null +++ b/release-notes/images/1_9/configure-lang-mode.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:62c0fca0f23ef3695c3d9d856c4e4173351d66649c9c933f1799b0165ebe01d2 +size 105542 diff --git a/release-notes/images/1_9/confirming-php.png b/release-notes/images/1_9/confirming-php.png new file mode 100644 index 0000000000000000000000000000000000000000..dd1e34cea817dee56a71071ed457eda2baeff24c Binary files /dev/null and b/release-notes/images/1_9/confirming-php.png differ diff --git a/release-notes/images/1_9/copy_stack.png b/release-notes/images/1_9/copy_stack.png new file mode 100644 index 0000000000000000000000000000000000000000..19ff5214387c0cf90b04105c027dfb03f0a8d657 Binary files /dev/null and b/release-notes/images/1_9/copy_stack.png differ diff --git a/release-notes/images/1_9/dimmed-callstack.png b/release-notes/images/1_9/dimmed-callstack.png new file mode 100644 index 0000000000000000000000000000000000000000..898d1a2a8bd4960cc3c7eb7a95f671b1ea321fea Binary files /dev/null and b/release-notes/images/1_9/dimmed-callstack.png differ diff --git a/release-notes/images/1_9/extensionpack-generator.png b/release-notes/images/1_9/extensionpack-generator.png new file mode 100644 index 0000000000000000000000000000000000000000..3a85cb5861c1587517bf34d8a5ecbe7b849e9eaf Binary files /dev/null and b/release-notes/images/1_9/extensionpack-generator.png differ diff --git a/release-notes/images/1_9/inline_values.png b/release-notes/images/1_9/inline_values.png new file mode 100644 index 0000000000000000000000000000000000000000..4e26bd3860290ccfcca6ef9294b726f1c4314a7c --- /dev/null +++ b/release-notes/images/1_9/inline_values.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8ce3f4bd33f77e380ee3534b834703f4fdc73c7890090af52481c260ad9cb973 +size 264841 diff --git a/release-notes/images/1_9/inspect-tm-scopes.png b/release-notes/images/1_9/inspect-tm-scopes.png new file mode 100644 index 0000000000000000000000000000000000000000..a09fb2d8432414d050e658281d1aaa98921ef0bc Binary files /dev/null and b/release-notes/images/1_9/inspect-tm-scopes.png differ diff --git a/release-notes/images/1_9/interactive-playground.png b/release-notes/images/1_9/interactive-playground.png new file mode 100644 index 0000000000000000000000000000000000000000..97febf8eb782e83738f9c841b9462e5347d35b0a Binary files /dev/null and b/release-notes/images/1_9/interactive-playground.png differ diff --git a/release-notes/images/1_9/interface-overview.png b/release-notes/images/1_9/interface-overview.png new file mode 100644 index 0000000000000000000000000000000000000000..4843c647831344b51200ff26b4ec74460a8766aa Binary files /dev/null and b/release-notes/images/1_9/interface-overview.png differ diff --git a/release-notes/images/1_9/lang-based-settings.png b/release-notes/images/1_9/lang-based-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..91c4df229c9e882a9909e754c56f1a47f4d7d2a1 Binary files /dev/null and b/release-notes/images/1_9/lang-based-settings.png differ diff --git a/release-notes/images/1_9/lang-selection.png b/release-notes/images/1_9/lang-selection.png new file mode 100644 index 0000000000000000000000000000000000000000..3eef7fc55b0aa7cfc498bd2991a4a4d421de44a8 Binary files /dev/null and b/release-notes/images/1_9/lang-selection.png differ diff --git a/release-notes/images/1_9/language-mode.png b/release-notes/images/1_9/language-mode.png new file mode 100644 index 0000000000000000000000000000000000000000..16d0e3869bd351f80c75d74f05674f57d9e7b98a Binary files /dev/null and b/release-notes/images/1_9/language-mode.png differ diff --git a/release-notes/images/1_9/launch-snippets.png b/release-notes/images/1_9/launch-snippets.png new file mode 100644 index 0000000000000000000000000000000000000000..4b729a28593f21714df6a741d49d69c7f31a90cc Binary files /dev/null and b/release-notes/images/1_9/launch-snippets.png differ diff --git a/release-notes/images/1_9/log-objects.png b/release-notes/images/1_9/log-objects.png new file mode 100644 index 0000000000000000000000000000000000000000..27bd1d661c384dc4022551c18529f86e4eb3d78e --- /dev/null +++ b/release-notes/images/1_9/log-objects.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:42cd004a14ce989420635c76d3765422c54dad8297cfa183928d69b09f2f1252 +size 178696 diff --git a/release-notes/images/1_9/markdown-double-click-preview-switch.gif b/release-notes/images/1_9/markdown-double-click-preview-switch.gif new file mode 100644 index 0000000000000000000000000000000000000000..f0be7cd15215f31a5210ceb51118ece7187bcd94 --- /dev/null +++ b/release-notes/images/1_9/markdown-double-click-preview-switch.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3c86088acd55ee8a08ee8517a085ad7ef7b3d9163721b225f1015e79157e2ea9 +size 593482 diff --git a/release-notes/images/1_9/markdown-preview-to-editor-scroll-sync.gif b/release-notes/images/1_9/markdown-preview-to-editor-scroll-sync.gif new file mode 100644 index 0000000000000000000000000000000000000000..603869a542ff05c9fc7687dbc3de41f743e05d5a --- /dev/null +++ b/release-notes/images/1_9/markdown-preview-to-editor-scroll-sync.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:82d3a359b6bd1284ead0f889632697b1d9619b980ce754a0165b56c7fd497fca +size 6811390 diff --git a/release-notes/images/1_9/markdown-selection-preview-scroll-sync.gif b/release-notes/images/1_9/markdown-selection-preview-scroll-sync.gif new file mode 100644 index 0000000000000000000000000000000000000000..0327cddd825edec7c47067057d653e68f4e4edea --- /dev/null +++ b/release-notes/images/1_9/markdown-selection-preview-scroll-sync.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7419a27374ee81465bec87f90f129a6f73d1efe52d5b77089588ffbd0f18163f +size 4350874 diff --git a/release-notes/images/1_9/no_folder_debug.gif b/release-notes/images/1_9/no_folder_debug.gif new file mode 100644 index 0000000000000000000000000000000000000000..768172f53f91e3140342c4a63f5b11beacd2acc4 --- /dev/null +++ b/release-notes/images/1_9/no_folder_debug.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a18fe61a1ddcb8250338bc459f95af9a8fc638ee8367fa328cbea386eee9e6c5 +size 514173 diff --git a/release-notes/images/1_9/output_scroll_lock.png b/release-notes/images/1_9/output_scroll_lock.png new file mode 100644 index 0000000000000000000000000000000000000000..5c8794fd9cfea6169f545682fa95d17c72208d61 Binary files /dev/null and b/release-notes/images/1_9/output_scroll_lock.png differ diff --git a/release-notes/images/1_9/panel.png b/release-notes/images/1_9/panel.png new file mode 100644 index 0000000000000000000000000000000000000000..70a9ed99c2039b582c41802940abf56a1c8c4559 Binary files /dev/null and b/release-notes/images/1_9/panel.png differ diff --git a/release-notes/images/1_9/pref-config-lang-settings.png b/release-notes/images/1_9/pref-config-lang-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..6f724263cd273c717c989a8e9d4e19af0de77e6b Binary files /dev/null and b/release-notes/images/1_9/pref-config-lang-settings.png differ diff --git a/release-notes/images/1_9/release-highlights.png b/release-notes/images/1_9/release-highlights.png new file mode 100644 index 0000000000000000000000000000000000000000..999f1ec946ff0a4f564b3254d9e0faaeedf4fc74 Binary files /dev/null and b/release-notes/images/1_9/release-highlights.png differ diff --git a/release-notes/images/1_9/search-result-nav.gif b/release-notes/images/1_9/search-result-nav.gif new file mode 100644 index 0000000000000000000000000000000000000000..d79eb7a43869fbe77a43f34eb0931b345b141404 --- /dev/null +++ b/release-notes/images/1_9/search-result-nav.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b667300208aa6684996dd3fbe2a09753760968692343a582e4bc865f49e0a966 +size 505226 diff --git a/release-notes/images/1_9/settings.png b/release-notes/images/1_9/settings.png new file mode 100644 index 0000000000000000000000000000000000000000..6bb95f93e91f1f874bd2f4c7aa07b30c495bc0f7 --- /dev/null +++ b/release-notes/images/1_9/settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:90db9f4bf117d70fba3e179251392b337bb59c5872e97715f66fae43c1cc0f6b +size 118147 diff --git a/release-notes/images/1_9/tab-context.png b/release-notes/images/1_9/tab-context.png new file mode 100644 index 0000000000000000000000000000000000000000..5ed9018a251eaa7e15756831bc46c97b1216357b Binary files /dev/null and b/release-notes/images/1_9/tab-context.png differ diff --git a/release-notes/images/1_9/tabclose.png b/release-notes/images/1_9/tabclose.png new file mode 100644 index 0000000000000000000000000000000000000000..bcbb0a1a08ac6029694177bde6aa0d5bb39840cb Binary files /dev/null and b/release-notes/images/1_9/tabclose.png differ diff --git a/release-notes/images/1_9/tasks.gif b/release-notes/images/1_9/tasks.gif new file mode 100644 index 0000000000000000000000000000000000000000..bf96b65d8285e3bf4ad334dc80518529fbe36466 --- /dev/null +++ b/release-notes/images/1_9/tasks.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a9a666f67d14b1679d80b67888956a3c783ea7dfaf3b5e75c1e32289f5e7e43c +size 256551 diff --git a/release-notes/images/1_9/terminal-after.gif b/release-notes/images/1_9/terminal-after.gif new file mode 100644 index 0000000000000000000000000000000000000000..3e834ffe420e2f15be29b46029a5dfa2e8ed0e85 --- /dev/null +++ b/release-notes/images/1_9/terminal-after.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9f1c710a46a730ed3f21fb9960ae06f794716c9e7b60c799d3cd5ba445b5374e +size 418639 diff --git a/release-notes/images/1_9/terminal-before.gif b/release-notes/images/1_9/terminal-before.gif new file mode 100644 index 0000000000000000000000000000000000000000..c4e97632762c58df65f85ba75a2ca224ce60976d Binary files /dev/null and b/release-notes/images/1_9/terminal-before.gif differ diff --git a/release-notes/images/1_9/toggle-skip-file.png b/release-notes/images/1_9/toggle-skip-file.png new file mode 100644 index 0000000000000000000000000000000000000000..3fb0ef17c14dcd0bf88f9be27774fc6301e60384 --- /dev/null +++ b/release-notes/images/1_9/toggle-skip-file.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1321bd38d55aed85e823e1d14c4746f48f954689b9ec72cf09d5f4b1558b5e5c +size 193599 diff --git a/release-notes/images/1_9/ts-references-code-lens-peek.png b/release-notes/images/1_9/ts-references-code-lens-peek.png new file mode 100644 index 0000000000000000000000000000000000000000..e1c3cae21b9ea94d9f9385a702b54023e2ff3403 Binary files /dev/null and b/release-notes/images/1_9/ts-references-code-lens-peek.png differ diff --git a/release-notes/images/1_9/ts-references-code-lens.png b/release-notes/images/1_9/ts-references-code-lens.png new file mode 100644 index 0000000000000000000000000000000000000000..12ec9bba0d6578f3b7b887542cb031685094d4f8 Binary files /dev/null and b/release-notes/images/1_9/ts-references-code-lens.png differ diff --git a/release-notes/images/1_9/ts-select-ts-version-message.png b/release-notes/images/1_9/ts-select-ts-version-message.png new file mode 100644 index 0000000000000000000000000000000000000000..360262a45c439968641b9629786d4444971e1875 Binary files /dev/null and b/release-notes/images/1_9/ts-select-ts-version-message.png differ diff --git a/release-notes/images/1_9/ts-status-bar-version.png b/release-notes/images/1_9/ts-status-bar-version.png new file mode 100644 index 0000000000000000000000000000000000000000..bf6e62233e979e1d9d6854151319bbcfe62b7897 Binary files /dev/null and b/release-notes/images/1_9/ts-status-bar-version.png differ diff --git a/release-notes/images/1_9/welcome-page.png b/release-notes/images/1_9/welcome-page.png new file mode 100644 index 0000000000000000000000000000000000000000..566adc15926af25abc052d27e0accf82866c7af0 Binary files /dev/null and b/release-notes/images/1_9/welcome-page.png differ diff --git a/release-notes/images/April/call-stack-paging.png b/release-notes/images/April/call-stack-paging.png new file mode 100644 index 0000000000000000000000000000000000000000..2266dfcd524a54ed8718f43450334016a2b59a55 Binary files /dev/null and b/release-notes/images/April/call-stack-paging.png differ diff --git a/release-notes/images/April/es6-generator-support.png b/release-notes/images/April/es6-generator-support.png new file mode 100644 index 0000000000000000000000000000000000000000..2691dbcf7aae6dfb948fee44a6e0661e0bbd68db Binary files /dev/null and b/release-notes/images/April/es6-generator-support.png differ diff --git a/release-notes/images/April/es6-map-support.png b/release-notes/images/April/es6-map-support.png new file mode 100644 index 0000000000000000000000000000000000000000..4b5f5b24d5fc0aeaad1700f9bd85d5735a6a7b12 Binary files /dev/null and b/release-notes/images/April/es6-map-support.png differ diff --git a/release-notes/images/April/es6-set-support.png b/release-notes/images/April/es6-set-support.png new file mode 100644 index 0000000000000000000000000000000000000000..7adc8be5ce655a0490f0bfb5b8c3ff29b9ebe5b9 Binary files /dev/null and b/release-notes/images/April/es6-set-support.png differ diff --git a/release-notes/images/April/smartStepping.gif b/release-notes/images/April/smartStepping.gif new file mode 100644 index 0000000000000000000000000000000000000000..92b3e36598f4a8a2cc8629e4e0df8c88469a60fb --- /dev/null +++ b/release-notes/images/April/smartStepping.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b35a0b8bae5cf49369a3fa46bf62f880991f19a6b33e1298201836cfc9859d6b +size 2531474 diff --git a/release-notes/images/December/debug-repl-wrap.png b/release-notes/images/December/debug-repl-wrap.png new file mode 100644 index 0000000000000000000000000000000000000000..c1999e0ef2c02e53d2ef746741beda90ffbcec84 Binary files /dev/null and b/release-notes/images/December/debug-repl-wrap.png differ diff --git a/release-notes/images/December/extension-issues.png b/release-notes/images/December/extension-issues.png new file mode 100644 index 0000000000000000000000000000000000000000..37e30417bd4a60ae3c6a5ba19d5df8508c2b1bf5 Binary files /dev/null and b/release-notes/images/December/extension-issues.png differ diff --git a/release-notes/images/December/fuzzy-search.png b/release-notes/images/December/fuzzy-search.png new file mode 100644 index 0000000000000000000000000000000000000000..f376fcd995a3a4c3893993a4aefb17af126eb368 Binary files /dev/null and b/release-notes/images/December/fuzzy-search.png differ diff --git a/release-notes/images/December/git-status-bar-publish.png b/release-notes/images/December/git-status-bar-publish.png new file mode 100644 index 0000000000000000000000000000000000000000..7da1d56dacb597d753e20cc2a9f264cd53185801 Binary files /dev/null and b/release-notes/images/December/git-status-bar-publish.png differ diff --git a/release-notes/images/December/git-status-bar-sync.png b/release-notes/images/December/git-status-bar-sync.png new file mode 100644 index 0000000000000000000000000000000000000000..af1b8ed847878a3d1a933d3d51bc4f0614d560e7 Binary files /dev/null and b/release-notes/images/December/git-status-bar-sync.png differ diff --git a/release-notes/images/December/key-binding-widget.png b/release-notes/images/December/key-binding-widget.png new file mode 100644 index 0000000000000000000000000000000000000000..d13e16cdc47befab28760f89ad893538460d369f Binary files /dev/null and b/release-notes/images/December/key-binding-widget.png differ diff --git a/release-notes/images/December/keybindings-json.png b/release-notes/images/December/keybindings-json.png new file mode 100644 index 0000000000000000000000000000000000000000..570f3d5ae5c513020916b71c45a72862539c45fe Binary files /dev/null and b/release-notes/images/December/keybindings-json.png differ diff --git a/release-notes/images/December/path-search.png b/release-notes/images/December/path-search.png new file mode 100644 index 0000000000000000000000000000000000000000..b710c0a0e8a6e63c928315a00372a969b15d9758 Binary files /dev/null and b/release-notes/images/December/path-search.png differ diff --git a/release-notes/images/December/render-key-binding.png b/release-notes/images/December/render-key-binding.png new file mode 100644 index 0000000000000000000000000000000000000000..16078ce8d37e4b608e405496a6df591bcf37f097 Binary files /dev/null and b/release-notes/images/December/render-key-binding.png differ diff --git a/release-notes/images/February/breakpoint-exclam.png b/release-notes/images/February/breakpoint-exclam.png new file mode 100644 index 0000000000000000000000000000000000000000..341477e83263174734c0a63d86f39168f49e9c8f Binary files /dev/null and b/release-notes/images/February/breakpoint-exclam.png differ diff --git a/release-notes/images/February/breakpoint-options.png b/release-notes/images/February/breakpoint-options.png new file mode 100644 index 0000000000000000000000000000000000000000..8482df4c167f8ca7582298f6207c936e48e24cff Binary files /dev/null and b/release-notes/images/February/breakpoint-options.png differ diff --git a/release-notes/images/February/close-other-files.png b/release-notes/images/February/close-other-files.png new file mode 100644 index 0000000000000000000000000000000000000000..692bdde49493ab2d9b9ed700a1a919ad29743d58 Binary files /dev/null and b/release-notes/images/February/close-other-files.png differ diff --git a/release-notes/images/February/ext-csharp.png b/release-notes/images/February/ext-csharp.png new file mode 100644 index 0000000000000000000000000000000000000000..0c2ce634b4970db823f89e3f17c317b4ed96b319 Binary files /dev/null and b/release-notes/images/February/ext-csharp.png differ diff --git a/release-notes/images/February/extension-tips-2.png b/release-notes/images/February/extension-tips-2.png new file mode 100644 index 0000000000000000000000000000000000000000..9bf3ef46912413d1e5b474b8cd38b8a4621bb97b Binary files /dev/null and b/release-notes/images/February/extension-tips-2.png differ diff --git a/release-notes/images/February/folding.png b/release-notes/images/February/folding.png new file mode 100644 index 0000000000000000000000000000000000000000..3056e9400fdd12a9a91df1dcde44577aa5d47cb6 Binary files /dev/null and b/release-notes/images/February/folding.png differ diff --git a/release-notes/images/February/function-breakpoint.gif b/release-notes/images/February/function-breakpoint.gif new file mode 100644 index 0000000000000000000000000000000000000000..ac7c6701cb428db7dcdc7658dfc4f8401185f190 --- /dev/null +++ b/release-notes/images/February/function-breakpoint.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f78168b8350cba318f1b789a20d489889b9a546590526187fc77abab1b930265 +size 326636 diff --git a/release-notes/images/February/high-contrast.png b/release-notes/images/February/high-contrast.png new file mode 100644 index 0000000000000000000000000000000000000000..ac819b949f60b1c2540dd237381937bfee95b002 --- /dev/null +++ b/release-notes/images/February/high-contrast.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4b23d6f353feb37af887121c1f704d73e414de895117d0cdff6829254f9b757c +size 116670 diff --git a/release-notes/images/February/indentation-1.png b/release-notes/images/February/indentation-1.png new file mode 100644 index 0000000000000000000000000000000000000000..0bdf4fd1fd65536b774ae371c7497a03e8028bc9 Binary files /dev/null and b/release-notes/images/February/indentation-1.png differ diff --git a/release-notes/images/February/indentation-2.png b/release-notes/images/February/indentation-2.png new file mode 100644 index 0000000000000000000000000000000000000000..7dc5caac83a9eb38ea3401e8e5029f7a9dd7e5b4 Binary files /dev/null and b/release-notes/images/February/indentation-2.png differ diff --git a/release-notes/images/February/mono-debug-install.png b/release-notes/images/February/mono-debug-install.png new file mode 100644 index 0000000000000000000000000000000000000000..ac5e13248bd692592f0968dd98209ec3f8406153 Binary files /dev/null and b/release-notes/images/February/mono-debug-install.png differ diff --git a/release-notes/images/February/open-definition-to-side.png b/release-notes/images/February/open-definition-to-side.png new file mode 100644 index 0000000000000000000000000000000000000000..20084907a6f22674c52ae0537bf068c3f7929cc7 Binary files /dev/null and b/release-notes/images/February/open-definition-to-side.png differ diff --git a/release-notes/images/February/pre-launch-task-error.png b/release-notes/images/February/pre-launch-task-error.png new file mode 100644 index 0000000000000000000000000000000000000000..8b99522a66a5bc4f84fd01404599cb19dc83dadf Binary files /dev/null and b/release-notes/images/February/pre-launch-task-error.png differ diff --git a/release-notes/images/February/quick-open-working-files.png b/release-notes/images/February/quick-open-working-files.png new file mode 100644 index 0000000000000000000000000000000000000000..16ac06487fc4f807188179032051ca5a69ab05b7 Binary files /dev/null and b/release-notes/images/February/quick-open-working-files.png differ diff --git a/release-notes/images/February/react-native.png b/release-notes/images/February/react-native.png new file mode 100644 index 0000000000000000000000000000000000000000..0948aeb5580faafd54f8a321a871a274792360ed Binary files /dev/null and b/release-notes/images/February/react-native.png differ diff --git a/release-notes/images/February/relative-path-error.png b/release-notes/images/February/relative-path-error.png new file mode 100644 index 0000000000000000000000000000000000000000..3cd8f90cf57ab03e938587b40faa8a18b1893f23 Binary files /dev/null and b/release-notes/images/February/relative-path-error.png differ diff --git a/release-notes/images/February/shell-command.png b/release-notes/images/February/shell-command.png new file mode 100644 index 0000000000000000000000000000000000000000..40583c273fc54e87906c0ee03c8caf0f21d48f8d Binary files /dev/null and b/release-notes/images/February/shell-command.png differ diff --git a/release-notes/images/January/api-virtual-documents.png b/release-notes/images/January/api-virtual-documents.png new file mode 100644 index 0000000000000000000000000000000000000000..5f347bb281d3f82737b5a20ab674dac3b4ddb252 --- /dev/null +++ b/release-notes/images/January/api-virtual-documents.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:68f2b9955492eb37e22364262210c201cc71337700c05bf48b1ce02a8084d0bf +size 105928 diff --git a/release-notes/images/January/conditional-breakpoints.png b/release-notes/images/January/conditional-breakpoints.png new file mode 100644 index 0000000000000000000000000000000000000000..91f5558fba21e3191854d3c3c342ddf352addbb2 Binary files /dev/null and b/release-notes/images/January/conditional-breakpoints.png differ diff --git a/release-notes/images/January/dark_plus_theme.png b/release-notes/images/January/dark_plus_theme.png new file mode 100644 index 0000000000000000000000000000000000000000..7c26e1938a888d1695bde2fd70de379fbce20cc6 Binary files /dev/null and b/release-notes/images/January/dark_plus_theme.png differ diff --git a/release-notes/images/January/debug-hover.png b/release-notes/images/January/debug-hover.png new file mode 100644 index 0000000000000000000000000000000000000000..5fa8ee00c16d6310320e4b25194f3a9d634b82b8 Binary files /dev/null and b/release-notes/images/January/debug-hover.png differ diff --git a/release-notes/images/January/debug-inlined-source.png b/release-notes/images/January/debug-inlined-source.png new file mode 100644 index 0000000000000000000000000000000000000000..dfb146d2504122c7977b442071179d71e6bd0b93 Binary files /dev/null and b/release-notes/images/January/debug-inlined-source.png differ diff --git a/release-notes/images/January/editor-ligatures.png b/release-notes/images/January/editor-ligatures.png new file mode 100644 index 0000000000000000000000000000000000000000..d6eb4eac5ec45b19e29c75079d2e3a41282e0257 Binary files /dev/null and b/release-notes/images/January/editor-ligatures.png differ diff --git a/release-notes/images/January/es3-classes.png b/release-notes/images/January/es3-classes.png new file mode 100644 index 0000000000000000000000000000000000000000..befd0c2e425582622c5b239e29f6de63428f410d Binary files /dev/null and b/release-notes/images/January/es3-classes.png differ diff --git a/release-notes/images/January/find-widget-counts.png b/release-notes/images/January/find-widget-counts.png new file mode 100644 index 0000000000000000000000000000000000000000..c3b69971670218f56895bb075a52f017d3b0c646 Binary files /dev/null and b/release-notes/images/January/find-widget-counts.png differ diff --git a/release-notes/images/January/german-vscode.png b/release-notes/images/January/german-vscode.png new file mode 100644 index 0000000000000000000000000000000000000000..d6bdf0d4684b89dfa5c4bd7628957e8685f01ff1 Binary files /dev/null and b/release-notes/images/January/german-vscode.png differ diff --git a/release-notes/images/January/intellisense-1.png b/release-notes/images/January/intellisense-1.png new file mode 100644 index 0000000000000000000000000000000000000000..3a23081a21d0c0c126a68a2c03d3667d64848d82 Binary files /dev/null and b/release-notes/images/January/intellisense-1.png differ diff --git a/release-notes/images/January/intellisense-2.png b/release-notes/images/January/intellisense-2.png new file mode 100644 index 0000000000000000000000000000000000000000..5c7c248f8cb78b124d4302f74d35b39d4b7174db Binary files /dev/null and b/release-notes/images/January/intellisense-2.png differ diff --git a/release-notes/images/January/jsdoc.png b/release-notes/images/January/jsdoc.png new file mode 100644 index 0000000000000000000000000000000000000000..8d1161692a61f0f56855ed92246b37b7fe46debb Binary files /dev/null and b/release-notes/images/January/jsdoc.png differ diff --git a/release-notes/images/January/jsx-salsa.png b/release-notes/images/January/jsx-salsa.png new file mode 100644 index 0000000000000000000000000000000000000000..24b79cada8d79538e217f7e94678847fa81371bd Binary files /dev/null and b/release-notes/images/January/jsx-salsa.png differ diff --git a/release-notes/images/January/light_plus_theme.png b/release-notes/images/January/light_plus_theme.png new file mode 100644 index 0000000000000000000000000000000000000000..ebbd2277221267ed10e0fc98d9d00dc53ee53acd Binary files /dev/null and b/release-notes/images/January/light_plus_theme.png differ diff --git a/release-notes/images/January/output.png b/release-notes/images/January/output.png new file mode 100644 index 0000000000000000000000000000000000000000..d37c37b0cb99770355832d0c7c76ac4288558546 Binary files /dev/null and b/release-notes/images/January/output.png differ diff --git a/release-notes/images/January/salsa-commonjs.png b/release-notes/images/January/salsa-commonjs.png new file mode 100644 index 0000000000000000000000000000000000000000..2747de22f13f2d409cc0bd716c0b3366dccf0b85 Binary files /dev/null and b/release-notes/images/January/salsa-commonjs.png differ diff --git a/release-notes/images/January/salsa-status-failure.png b/release-notes/images/January/salsa-status-failure.png new file mode 100644 index 0000000000000000000000000000000000000000..f18b67f02a1bb5a429b3123389c7982ba4eb0ca3 Binary files /dev/null and b/release-notes/images/January/salsa-status-failure.png differ diff --git a/release-notes/images/January/salsa-status.png b/release-notes/images/January/salsa-status.png new file mode 100644 index 0000000000000000000000000000000000000000..29c9985eca7e377e1e590c5ef74349f52c56696a Binary files /dev/null and b/release-notes/images/January/salsa-status.png differ diff --git a/release-notes/images/January/variables-change.png b/release-notes/images/January/variables-change.png new file mode 100644 index 0000000000000000000000000000000000000000..44a5d28928c2c19f88af31785478b5bc34d75124 Binary files /dev/null and b/release-notes/images/January/variables-change.png differ diff --git a/release-notes/images/July_2016/editor-actions-title.png b/release-notes/images/July_2016/editor-actions-title.png new file mode 100644 index 0000000000000000000000000000000000000000..088841bf666d2c15c7b5f1fe3d19ba5336074746 Binary files /dev/null and b/release-notes/images/July_2016/editor-actions-title.png differ diff --git a/release-notes/images/July_2016/groupSorting.png b/release-notes/images/July_2016/groupSorting.png new file mode 100644 index 0000000000000000000000000000000000000000..d9dd9cd87ceeac900f884241c203636946f42c55 Binary files /dev/null and b/release-notes/images/July_2016/groupSorting.png differ diff --git a/release-notes/images/July_2016/insertSnippet.gif b/release-notes/images/July_2016/insertSnippet.gif new file mode 100644 index 0000000000000000000000000000000000000000..9b0e445f720403eb019aa4969528f0b60ed23b01 --- /dev/null +++ b/release-notes/images/July_2016/insertSnippet.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0c03fa0547f2ceaa530938a5cf6a11d0f4be9095f290e5416f293ca9860ac89e +size 690304 diff --git a/release-notes/images/July_2016/restartFrame.gif b/release-notes/images/July_2016/restartFrame.gif new file mode 100644 index 0000000000000000000000000000000000000000..3415eb5031f99b3fc587537c42d6b5a30fcf0ea3 --- /dev/null +++ b/release-notes/images/July_2016/restartFrame.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:08cf8018065b7234aad9eee9e8177cee478a501f2c6a0217f56dc4f1c49af7fd +size 1453280 diff --git a/release-notes/images/July_2016/social.jpg b/release-notes/images/July_2016/social.jpg new file mode 100644 index 0000000000000000000000000000000000000000..9453eee1d98f03665fd4b7faa5015bc1577e4859 Binary files /dev/null and b/release-notes/images/July_2016/social.jpg differ diff --git a/release-notes/images/July_2016/tabCompletion.gif b/release-notes/images/July_2016/tabCompletion.gif new file mode 100644 index 0000000000000000000000000000000000000000..21bdeb09f6d6a4bcb124ff7b45d11f27930c56b4 --- /dev/null +++ b/release-notes/images/July_2016/tabCompletion.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:28114fad6c7552a7b474f6f0c60b6babcbc4d839fabf886a5f2ede2444189a51 +size 842489 diff --git a/release-notes/images/July_2016/terminal_ime.png b/release-notes/images/July_2016/terminal_ime.png new file mode 100644 index 0000000000000000000000000000000000000000..db9d43500a8b8cde543d59ce3809fc720f52f7a4 Binary files /dev/null and b/release-notes/images/July_2016/terminal_ime.png differ diff --git a/release-notes/images/July_2016/variablePaging.png b/release-notes/images/July_2016/variablePaging.png new file mode 100644 index 0000000000000000000000000000000000000000..f2d90eb7c6b533c5dfb1107e056547e8e9bc29bf Binary files /dev/null and b/release-notes/images/July_2016/variablePaging.png differ diff --git a/release-notes/images/June_2016/attach_to_process.png b/release-notes/images/June_2016/attach_to_process.png new file mode 100644 index 0000000000000000000000000000000000000000..5af74cd4251e5bc46adf514d0537a898f1f1498e Binary files /dev/null and b/release-notes/images/June_2016/attach_to_process.png differ diff --git a/release-notes/images/June_2016/color_decorators.png b/release-notes/images/June_2016/color_decorators.png new file mode 100644 index 0000000000000000000000000000000000000000..575ece9cd1e4d2f14bbbb07a0b531a694721f3c0 Binary files /dev/null and b/release-notes/images/June_2016/color_decorators.png differ diff --git a/release-notes/images/June_2016/commad_ids.png b/release-notes/images/June_2016/commad_ids.png new file mode 100644 index 0000000000000000000000000000000000000000..c59f916ba816f8880d1bda76ee67863879705d3d Binary files /dev/null and b/release-notes/images/June_2016/commad_ids.png differ diff --git a/release-notes/images/June_2016/dnd_debug.gif b/release-notes/images/June_2016/dnd_debug.gif new file mode 100644 index 0000000000000000000000000000000000000000..ab1f509ccebe0ee9d2ebce24ae207489b03c9700 Binary files /dev/null and b/release-notes/images/June_2016/dnd_debug.gif differ diff --git a/release-notes/images/June_2016/dnd_editor.gif b/release-notes/images/June_2016/dnd_editor.gif new file mode 100644 index 0000000000000000000000000000000000000000..90496c9e6f55fcb47679c853b6b34065253d98ea --- /dev/null +++ b/release-notes/images/June_2016/dnd_editor.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:29e81289427d38f03878437ae78588dd0dac522779dc30b2c24e3556d36da18f +size 457165 diff --git a/release-notes/images/June_2016/editor-indent-guides.jpg b/release-notes/images/June_2016/editor-indent-guides.jpg new file mode 100644 index 0000000000000000000000000000000000000000..062ee1e4f23c7b08ae441519d874b6dfb8026b33 Binary files /dev/null and b/release-notes/images/June_2016/editor-indent-guides.jpg differ diff --git a/release-notes/images/June_2016/editor-mouse-wheel-zoom.gif b/release-notes/images/June_2016/editor-mouse-wheel-zoom.gif new file mode 100644 index 0000000000000000000000000000000000000000..222197e1c3da643eb73aa350f7dbabc625e752c0 --- /dev/null +++ b/release-notes/images/June_2016/editor-mouse-wheel-zoom.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:56c09ab6711c6dd25dbe3281a38e5906fd2483f7cbe2a1aed0865eb799dc62e8 +size 1620339 diff --git a/release-notes/images/June_2016/extensions-view-icon.png b/release-notes/images/June_2016/extensions-view-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..59daa52e656823c63ac5a4676d063afd0c0bb1d4 Binary files /dev/null and b/release-notes/images/June_2016/extensions-view-icon.png differ diff --git a/release-notes/images/June_2016/extensions_viewlet.png b/release-notes/images/June_2016/extensions_viewlet.png new file mode 100644 index 0000000000000000000000000000000000000000..cc26997fbae26b05505b958047105b3919858ef3 --- /dev/null +++ b/release-notes/images/June_2016/extensions_viewlet.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a460111829b33388b7c3bcd54c1e36b364fe314d0d9888584afbbb3fce5a7cb6 +size 129834 diff --git a/release-notes/images/June_2016/menus-contributions.png b/release-notes/images/June_2016/menus-contributions.png new file mode 100644 index 0000000000000000000000000000000000000000..58d3166f9be66699a4655e2783a3ed5f3d83b9f4 Binary files /dev/null and b/release-notes/images/June_2016/menus-contributions.png differ diff --git a/release-notes/images/June_2016/monaco-editor-playground.png b/release-notes/images/June_2016/monaco-editor-playground.png new file mode 100644 index 0000000000000000000000000000000000000000..e8ae1c8be87bb8784cee3fd2bca85783193527df Binary files /dev/null and b/release-notes/images/June_2016/monaco-editor-playground.png differ diff --git a/release-notes/images/June_2016/multiline-find.gif b/release-notes/images/June_2016/multiline-find.gif new file mode 100644 index 0000000000000000000000000000000000000000..b348879011a155aee748a11f4687ade1c4eea262 --- /dev/null +++ b/release-notes/images/June_2016/multiline-find.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:42e02148f30e281f5a4b78a966f3a2af000bac7ed56f68c47867752f204d907f +size 216405 diff --git a/release-notes/images/June_2016/open_editors.png b/release-notes/images/June_2016/open_editors.png new file mode 100644 index 0000000000000000000000000000000000000000..0693a165a35f879fe4a9238db0cf9baa67885da6 Binary files /dev/null and b/release-notes/images/June_2016/open_editors.png differ diff --git a/release-notes/images/June_2016/overflow.png b/release-notes/images/June_2016/overflow.png new file mode 100644 index 0000000000000000000000000000000000000000..cdfc38db730e84abeb8e0805959c1e65e84450e4 Binary files /dev/null and b/release-notes/images/June_2016/overflow.png differ diff --git a/release-notes/images/June_2016/preview_editor.png b/release-notes/images/June_2016/preview_editor.png new file mode 100644 index 0000000000000000000000000000000000000000..912157780f9c0898b4f6370883e0f3a6946b5760 Binary files /dev/null and b/release-notes/images/June_2016/preview_editor.png differ diff --git a/release-notes/images/June_2016/problems.png b/release-notes/images/June_2016/problems.png new file mode 100644 index 0000000000000000000000000000000000000000..f48b696e2aaaaf0f81eb5e24650946cefcdee16c Binary files /dev/null and b/release-notes/images/June_2016/problems.png differ diff --git a/release-notes/images/June_2016/searchAndReplace.png b/release-notes/images/June_2016/searchAndReplace.png new file mode 100644 index 0000000000000000000000000000000000000000..7cb084192062c1b0fec66b6d0192f439ea7d1580 --- /dev/null +++ b/release-notes/images/June_2016/searchAndReplace.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5c9be1a2a038df7afe7b57c5a86851bb68bad9919b56d99d816d2c075151979e +size 206527 diff --git a/release-notes/images/June_2016/set_variable_value.gif b/release-notes/images/June_2016/set_variable_value.gif new file mode 100644 index 0000000000000000000000000000000000000000..f93b199cdfeaed5ff07b963a869361b7a9dda928 Binary files /dev/null and b/release-notes/images/June_2016/set_variable_value.gif differ diff --git a/release-notes/images/June_2016/social.jpg b/release-notes/images/June_2016/social.jpg new file mode 100644 index 0000000000000000000000000000000000000000..df6992bded69d17ac888e9664a6b9a47050864d3 --- /dev/null +++ b/release-notes/images/June_2016/social.jpg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:96d4b122dfb12d4dfc441855af13b505cc907fd3901231b69f78e6875dc9e261 +size 113142 diff --git a/release-notes/images/June_2016/stacks.png b/release-notes/images/June_2016/stacks.png new file mode 100644 index 0000000000000000000000000000000000000000..9f4ce21da35ba984b361f0e22c8a4790491663ac --- /dev/null +++ b/release-notes/images/June_2016/stacks.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:63ee3952aec406c58fdabe3de39ac0257a5be10037294cbb717ff0a6cca67965 +size 296592 diff --git a/release-notes/images/June_2016/step_back.png b/release-notes/images/June_2016/step_back.png new file mode 100644 index 0000000000000000000000000000000000000000..cdd3ef82c39c8b2c92e7b74b45875af8dc011f77 Binary files /dev/null and b/release-notes/images/June_2016/step_back.png differ diff --git a/release-notes/images/June_2016/tabs.png b/release-notes/images/June_2016/tabs.png new file mode 100644 index 0000000000000000000000000000000000000000..e450699953e6bfcc094186ed02adedcd64b6aa17 --- /dev/null +++ b/release-notes/images/June_2016/tabs.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ced1c7002a381663d88143e7f43b4ef6384abe26506d297378d38eeb338f3e83 +size 155367 diff --git a/release-notes/images/June_2016/terminal_multiple_instances.png b/release-notes/images/June_2016/terminal_multiple_instances.png new file mode 100644 index 0000000000000000000000000000000000000000..14da434bc9fa39327c650849d8785be2f83a1e6a Binary files /dev/null and b/release-notes/images/June_2016/terminal_multiple_instances.png differ diff --git a/release-notes/images/June_2016/terminal_run_selected.png b/release-notes/images/June_2016/terminal_run_selected.png new file mode 100644 index 0000000000000000000000000000000000000000..e67b000b7d390b7853bd6170b5ccd323f3386b2d Binary files /dev/null and b/release-notes/images/June_2016/terminal_run_selected.png differ diff --git a/release-notes/images/June_2016/terminal_run_selected_result.png b/release-notes/images/June_2016/terminal_run_selected_result.png new file mode 100644 index 0000000000000000000000000000000000000000..317a143d5709e154a19cf50ae52e094b744b837a Binary files /dev/null and b/release-notes/images/June_2016/terminal_run_selected_result.png differ diff --git a/release-notes/images/June_2016/terminal_selection.png b/release-notes/images/June_2016/terminal_selection.png new file mode 100644 index 0000000000000000000000000000000000000000..77e5bd2ed5c5179f73f6a02810b738055bfd9000 Binary files /dev/null and b/release-notes/images/June_2016/terminal_selection.png differ diff --git a/release-notes/images/March/column-select-mouse.gif b/release-notes/images/March/column-select-mouse.gif new file mode 100644 index 0000000000000000000000000000000000000000..4ca8846630fff44972d84aa8a6c5b7cbb68c9049 --- /dev/null +++ b/release-notes/images/March/column-select-mouse.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d54450e1d5f35de6c6e782c2a457b65d3ef4985bd2a223d3fa7b3c5994461b2a +size 468132 diff --git a/release-notes/images/March/diagnostics.png b/release-notes/images/March/diagnostics.png new file mode 100644 index 0000000000000000000000000000000000000000..cd9fef203756d71f5344e073b65aab7e306faca4 Binary files /dev/null and b/release-notes/images/March/diagnostics.png differ diff --git a/release-notes/images/March/extension-widget-notification.png b/release-notes/images/March/extension-widget-notification.png new file mode 100644 index 0000000000000000000000000000000000000000..ab39823d99e71bff776ab1aff4658ba75cb1272b Binary files /dev/null and b/release-notes/images/March/extension-widget-notification.png differ diff --git a/release-notes/images/March/extension-widget.png b/release-notes/images/March/extension-widget.png new file mode 100644 index 0000000000000000000000000000000000000000..4685d53997a83985d806a4c1c214a87641fa2a0d --- /dev/null +++ b/release-notes/images/March/extension-widget.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f2403b4ac621d95629609dbcba27ae85c2ebe1a3032d667013288ad2c9708801 +size 101136 diff --git a/release-notes/images/March/gitconfig.png b/release-notes/images/March/gitconfig.png new file mode 100644 index 0000000000000000000000000000000000000000..14811d6c0f860351ec4e70ef5cf19e0c6492145b Binary files /dev/null and b/release-notes/images/March/gitconfig.png differ diff --git a/release-notes/images/March/indentation.png b/release-notes/images/March/indentation.png new file mode 100644 index 0000000000000000000000000000000000000000..a0991dc01fa961ab7002d3b12da520d269b979c0 Binary files /dev/null and b/release-notes/images/March/indentation.png differ diff --git a/release-notes/images/March/jsconfig-hint.png b/release-notes/images/March/jsconfig-hint.png new file mode 100644 index 0000000000000000000000000000000000000000..ba1838192d4b98f8ff2e737b9e0a3e67870d22bd Binary files /dev/null and b/release-notes/images/March/jsconfig-hint.png differ diff --git a/release-notes/images/March/jsconfig-template.png b/release-notes/images/March/jsconfig-template.png new file mode 100644 index 0000000000000000000000000000000000000000..7fcb4a465ab066907378fde6915fc1ff4d842cba Binary files /dev/null and b/release-notes/images/March/jsconfig-template.png differ diff --git a/release-notes/images/March/language.png b/release-notes/images/March/language.png new file mode 100644 index 0000000000000000000000000000000000000000..0a346bf0b2bf5e5a29c9c993683ff1068e43b885 Binary files /dev/null and b/release-notes/images/March/language.png differ diff --git a/release-notes/images/March/statusbar_bom.png b/release-notes/images/March/statusbar_bom.png new file mode 100644 index 0000000000000000000000000000000000000000..e4fd88f3ed05075ab3c90b43add8dacc25af0de8 Binary files /dev/null and b/release-notes/images/March/statusbar_bom.png differ diff --git a/release-notes/images/March/tasks.png b/release-notes/images/March/tasks.png new file mode 100644 index 0000000000000000000000000000000000000000..fff1defa4e4f8b213afa57cd73d7d74747c759ee Binary files /dev/null and b/release-notes/images/March/tasks.png differ diff --git a/release-notes/images/May_2016/css-peek-definition.png b/release-notes/images/May_2016/css-peek-definition.png new file mode 100644 index 0000000000000000000000000000000000000000..464158c512fa3aabc0aaf581f64b0a2a30558932 Binary files /dev/null and b/release-notes/images/May_2016/css-peek-definition.png differ diff --git a/release-notes/images/May_2016/integrated-terminal.png b/release-notes/images/May_2016/integrated-terminal.png new file mode 100644 index 0000000000000000000000000000000000000000..49cd4951a2abf24d921e69b8268740ad60a2675a Binary files /dev/null and b/release-notes/images/May_2016/integrated-terminal.png differ diff --git a/release-notes/images/May_2016/many-locals.png b/release-notes/images/May_2016/many-locals.png new file mode 100644 index 0000000000000000000000000000000000000000..8ce7ee8d77c2161de659b9d889f97ba2b356651b Binary files /dev/null and b/release-notes/images/May_2016/many-locals.png differ diff --git a/release-notes/images/May_2016/peek.gif b/release-notes/images/May_2016/peek.gif new file mode 100644 index 0000000000000000000000000000000000000000..a3aa09f1c678c364bd3c54191cceb809414edd6c --- /dev/null +++ b/release-notes/images/May_2016/peek.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a6674188e087e1a7163a329bf1ea58dda6efb103b0ea94c552c5ec1457392908 +size 1463330 diff --git a/release-notes/images/May_2016/selectAllFindMatches.gif b/release-notes/images/May_2016/selectAllFindMatches.gif new file mode 100644 index 0000000000000000000000000000000000000000..d28b52becd8969a3b25238bee7521619c04bf920 --- /dev/null +++ b/release-notes/images/May_2016/selectAllFindMatches.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d3b68720c812131d51ec25993148d7836c309bf61ca85a85d060340f860ceeb1 +size 393156 diff --git a/release-notes/images/May_2016/tabsprogress.png b/release-notes/images/May_2016/tabsprogress.png new file mode 100644 index 0000000000000000000000000000000000000000..e1142748b3b68774293579c369526ae66c929cd4 --- /dev/null +++ b/release-notes/images/May_2016/tabsprogress.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:650d8aad8f1ff1fa6dcfcba9f219e73dd10401be5401fdbf94e5b1ab89281261 +size 100843 diff --git a/release-notes/images/May_2016/trimAutoWhitespace.gif b/release-notes/images/May_2016/trimAutoWhitespace.gif new file mode 100644 index 0000000000000000000000000000000000000000..240e553153651db5d910de1f890120c85a7580c3 Binary files /dev/null and b/release-notes/images/May_2016/trimAutoWhitespace.gif differ diff --git a/release-notes/v0_3_0.md b/release-notes/v0_3_0.md new file mode 100644 index 0000000000000000000000000000000000000000..70074febdc40cc7bfc162a20effc6a87e43ee966 --- /dev/null +++ b/release-notes/v0_3_0.md @@ -0,0 +1,203 @@ +--- +Order: +TOCTitle: June 2015 +PageTitle: Visual Studio Code 0.3.0 +MetaDescription: Visual Studio Code 0.3.0 +--- +# June 2015 (0.3.0) + +Thank you for using Visual Studio Code and keep the feedback coming! Based on your feedback, we added some frequently requested enhancements and provided over 300 minor improvements and bug fixes. This release is available now and is just the start - from this point on, you should expect to see an update roughly every month. + +See [how to update](/docs/supporting/howtoupdate.md) to get the bits. Read on for details about the many changes in this release. + +## Key Bindings + +Based on user feedback (thanks!) we've decided to make some key binding changes. If you do not like our changes, you can always change key bindings as described in the [keybindings](/docs/getstarted/keybindings.md) documentation. + +* The native File Open dialog has been restored to `kb(workbench.action.files.openFile)`. We received strong feedback that using this key for the Code File Open dialog is confusing. +* The Code File Open dialog is now accessible via `kb(workbench.action.quickOpen)`. We needed to find a new key for the Code File Open dialog. Since many editors are now using `kb(workbench.action.quickOpen)` for their enriched File Open dialog, we decided to go with this trend. +* Go To Definition is now `kb(editor.action.revealDefinition)` (formerly `kbstyle(Ctrl+F12)` on Windows). Visual Studio users suggested to align Go To Definition with Visual Studio. This wasn’t an option in the past when the VS Code editor was running inside the browser, since F12 was opening the developer tools. +* `kbstyle(Cmd+Up)` and `kbstyle(Cmd+Down)` now work as expected on the Mac by jumping to the beginning and end of the file. +* Format code is now `kb(editor.action.format)` + +## Command line args +You can now create a new file from the command line. For a file that doesn't exist yet, append the file path to create it. VS Code will open it as a dirty (modified but not yet saved) file in the editor. + +`code mynewfile.js` + +You can open multiple folders and/or files from the command line. Just append multiple folder and/or file paths to open multiple sessions of VS Code. + +`code c:\myfolder1 c:\myfolder2 c:\myapp\program.cs` + + +You can also open a new session instead of restoring the previous session. Use a new switch, `-n` or `--new-window`, if you want to start VS Code without restoring the previous session. + +`code -n` + +## Editing + +### Multi-cursor +Here's multi-cursor improvements that we've made. + +* `kb(editor.action.addSelectionToNextFindMatch)` selects the word at the cursor, or the next occurrence of the current selection. +* `kb(editor.action.moveSelectionToNextFindMatch)` moves the last added cursor to next occurrence of the current selection. +* The two actions pick up the **matchCase** and **matchWholeWord** settings of the find widget. +* `kb(cursorUndo)` undoes the last cursor action, so if you added one cursor too many or made a mistake, press `kb(cursorUndo)` to return to the previous cursor state. +* Insert cursor above (`kb(editor.action.insertCursorAbove)`) and insert cursor below (`kb(editor.action.insertCursorBelow)`) now reveals the last added cursor, making it easier to work with multi-cursors spanning more than one screen height (i.e., working with 300 lines while only 80 fit in the screen). + +### Comment action +We added these changes for comment actions. + +* `kb(editor.action.addCommentLine)` now forces adding line comments. +* `kb(editor.action.removeCommentLine)` now forces uncommenting lines. (If multiple lines are selected, and not all of them have a line comment, the line comments will still be removed). +* `kb(editor.action.commentLine)` toggles line comment as before, but now inserts the line comment tokens aligned with the indentation of the selected code. It also will leave empty or whitespace-only lines untouched. `kb(editor.action.commentLine)` is also more forgiving with regards to selection state when toggling comments in languages which only support block comments, such as CSS or HTML. +* Toggle block comment (`kb(editor.action.blockComment)`) is also more forgiving related to selection state when toggling block comments. + +![Block comments](images/0_3_0/BlockComments.png) + +### Indentation +Pressing `kbstyle(Tab)` on an empty line will indent as much as needed to place the cursor at the correct starting position (i.e., not just insert a single indentation). + +### Shrink/expand selection +Quickly shrink or expand the current selection (applies to all languages). Trigger it with `kb(editor.action.smartSelect.shrink)` and `kb(editor.action.smartSelect.expand)` + +Here's an example of expanding the selection with `kb(editor.action.smartSelect.expand)`: + +![Expand selection](images/0_3_0/expandselection.gif) + +### Wrapping control +To improve readability, you can now control how long lines are wrapped and indented with a new setting, `editor.wrappingIndent`, in **settings.json**. The following values are available for `editor.wrappingIndent`: + +* `none`: When a line wraps, subsequent lines start at column 1. + + ![WrappingIndent set to none](images/0_3_0/WrappingIndentNone.png) + +* `same`: (This is the default.) When a line wraps, subsequent lines start at the same column used by the original line. + + ![WrappingIndent set to none](images/0_3_0/WrappingIndentSame.png) + +* `indent`: When a line wraps, subsequent lines are indented once relative to the original line. + + ![WrappingIndent set to indent](images/0_3_0/WrappingIndentIndent.png) + +## Debugging +In launch configurations, you can now use the `runtimeArgs` attribute. This is useful if you need to pass command line arguments to Node or Mono (not to the program being debugged). + +Starting a debug session on Linux now opens a terminal with support for input/output. + +TypeScript debugging now supports JavaScript source maps. Enable this by setting the `sourceMaps` attribute to `true` in the launch configuration. In addition, you can specify a TypeScript file with the `program` attribute. To generate source maps for your TypeScript files, compile with the `--sourcemap` option. + +Debugging is now supported in folder-less workspaces +For example, you can debug when if a folder is not active (e.g., when you choose **File**, **Close Folder** or **File**, **New Window**). VS Code displays a purple status bar when you are in folder-less debug mode. + +For exceptions thrown, via the code line marked in red, and for breakpoints, via the status bar. + +![Debugging UI](images/0_3_0/DebugVisualization.png) + +Here's other debugging changes we made for this release. + +* A icon to collapse all variables has been added to the Variables tree. +* You can now copy a variable's value to the clipboard from the Variables tree. +* Environment variables now work on all platforms. +* VS Code no longer inadvertently hijacks an arbitrary terminal on OS X when starting a launch session. Only a terminal previously used for debugging is reused for a new session. +* Arguments passed to the runtime or program being debugged can now contain spaces. +* `kbstyle(F9)` and `kbstyle(F11)` work again. +* Debugging works with UNC paths. +* Better error messages are provided if Mono or Node is missing. +* Support has been added for F# debugging on Mono on OS X and Linux + +## Tasks + +We have defined three new problem matchers: + +* `$jshint-stylish`: To detect jshint problems produced by the stylish reporter. +* `$eslint-compact`: To detect eslint problems produced by the compact reporter. +* `$eslint-stylish`: To detect eslint problems produced by the stylish reporter. + +Multiline problem matchers have been added to the task system to capture stylish output from several linting tools. You can see an example in [Tasks](/docs/editor/tasks.md). + +You can now consistently redefine global properties per operating system and per explicit task. See [operating specific values](/docs/editor/tasks.md#operating-system-specific-properties) and [task specific values](/docs/editor/tasks.md#task-specific-properties) for details. + +A new property, `suppressTaskName`, can be specified globally, per operating system, or per task, to indicate whether the task name is added to the arguments when a task command is executed. See more details in the Appendix of [Tasks](/docs/editor/tasks.md). + +## Languages + +### Rust +[Rust](https://www.rust-lang.org/) has been added as a supported language for colorization and bracket matching. + +### TypeScript +The TypeScript language service has been updated to TypeScript version 1.5. + +### JavaScript +New options allow you to turn off *all* semantic and syntax checks, useful if you prefer JSHint instead of the VS Code JavaScript validator. + +* `javascript.validate.semanticValidation=[true|false]` Use `true` to have VS Code report semantic errors (unassigned variables, etc. and *all* lint checks) +* `javascript.validate.syntaxValidation=[true|false]` Use `false` to have VS Code report syntaX errors (missing brackets, etc.). + +### HTML +HTML auto closing of tags has now been removed and replaced with smarter IntelliSense on `**Note:** In the Editor Options section below, we show how you can hide derived resources in the Explorer, update the size of the Working Files area and exclude files from Search. + +**New command line options: -r and -g** + +* The `-r` (or `--reuse-window`) command line option forces opening a file or folder in the last active window. This is useful in cases where you want to quickly send a file from the command line into your workspace, without having to manage new windows each time. This also works with files that don't exist - VS Code will simply open a new file as dirty in the last active window. + +* The `-g` (or `--goto`) command line option lets you open files at a specific line and column number. This is useful if you're using another tool in your workflow and want VS Code to open an exact position within a file.
The syntax is:
`code -g file1:: file2:: file3::`
The `column` value is optional. As shown in the example, you can open multiple files in a single VS Code instance using the desired line and column position. Note that `"-g"` switch is mandatory for this feature, since `:` is a valid character in file names on some operating systems.
+Here's how to open a file to line 10, column 17:
`code -g c:\mycode\HelloWorld.ts:10:17`
+ +>**Tip:** If you combine `-r` and `-g` you can configure an external tool to open files on a specific line and column into your running VS Code instance! This was a popular request from the Unity user base. + +**Additional command line changes** + +When you pass multiple file paths to VS Code, they will all open in the same instance now. If some of the paths point to files that don't exist, VS Code will open new files as dirty. + +When you pass in command line arguments for the path to a folder, and also a file name, VS Code will open both the folder and file in a single VS Code instance. Previously we would open two (or more) VS Code instances. The usage case is that you want to open a specific file in a folder while still opening the folder in the side bar. + +Note that you can use absolute paths or relative paths for the folder argument and the file argument. If you use a relative path for the file argument, it is relative to where you start VS Code (not relative to the folder argument). + +This example opens the current folder and a specific file, HelloWorld.ts, in that folder (the file will be created as dirty if it doesn't exist). + +`code . HelloWorld.ts` + +**Mac dock support** + +You can now open files and folders by dropping them to VS Code, even if it is not yet running. In addition, when you drop multiple files on the dock while VS Code is already running, VS Code will not start separate instances for each, but instead will try to open them in one instance. + +## Editor options + +We added more configuration options for files, explorer and search. Access them from **File** | **Preferences**. + +**Patterns syntax** + +To support several of the new Search and Editor options, we've introduced a lightweight pattern matcher. With a simplified set of patterns we support for specifying match patterns, you can use: + +* `*` to match one or more characters in a path segment +* `?` to match on one character in a path segment +* `**` to match any number of path segments ,including none +* `{}` to group conditions (e.g. `{**/*.html,**/*.txt}` matches all html and txt files) +* `[]` to declare a range of characters to match (e.g., `example.[0-9]` to match on `example.0`, `example.1`, … + +**Automatically trim trailing whitespace** + +By popular demand, we added the `files.trimTrailingWhitespace` setting that allows you to trim trailing whitespace whenever you save. This also works with autosave enabled. + +**Configure the size and behavior of Working Files** + +Two new settings give you more control over how files appear in the Working Files area - ideal for larger monitors! + +* The `explorer.workingFiles.maxVisible` setting allows you to configure the number of visible working files before a scrollbar appears (the default is 9). +* The `explorer.workingFiles.dynamicHeight` setting lets you configure whether working files should dynamically adjust its height based on the number of elements inside. Set this to `false` if you don’t want the explorer jumping down when you add new working files. The default is `true`. + +**Hiding files and folders** + +The `files.exclude` setting lets you define patterns to hide files and folders from several places in VS Code like the explorer and search. Once defined, files and folders matching any of the patterns will be hidden. + +>**Tip:** This is really useful to hide derived resources files, like `\*.meta` in Unity, or `\*.js` in a TypeScript project. For Unity to exclude the `\*.cs.meta` files, the pattern to choose would be: `"**/*.cs.meta"` + +**Hide derived resources** + +If you use a language that compiles to another file at the same location of the source file, like TypeScript does to JavaScript, you often don’t want to see the files in the explorer or include them in search results. With the new filtering capabilities, you can easily set an expression to hide those derived files: + +`"**/*.js": { "when": "$(basename).ts"}` + +Such a pattern will match on any JavaScript file (`**/*.js`), but only if a sibling file with the same name and extension, `*.ts` in this example, is present. The result being Explorer will no longer show derived resources for JavaScript if they are compiled to the same location. All you have to do is configure this in the `files.exclude` setting. While we've used JavaScript for this example, the same technique can be used for other transpiled languages, like Coffee Script or Less/Sass, too. + +Here's an example of how JavaScript files are hidden using the `"**/*.js": { "when": "$(basename).ts"}` expression. + +![Hiding derived resources](images/0_5_0/HidingDerivedResources.png) + +**Exclude files and folders from search** + +The `search.exclude` setting lets you configure additional files and folders to exclude from full text searches and from quick open, besides the `file.exclude` setting. This uses the patterns syntax (discussed below). + +>**Note:** This is a **breaking change**, as it replaces `search.excludeFolders`, so be sure to update your settings! + +**Search leveraging patterns** + +To let you define powerful patterns for includes and excludes when you run searches, we added glob pattern support to the search box too. You can enable glob pattern search by clicking on the little icon in the include and exclude box. + +Once you click on the pattern icon, you have access to the pattern reference. + +![Search patterns](images/0_5_0/SearchPatterns.png) + +>**Note:** You can still use wildcards without enabling glob pattern support. Things like `*.js` to search in all JavaScript files still work. Once you enable glob pattern syntax, keep in mind that you need to use `**/*.js` to search across all directories of your project! + +## JavaScript + +We've made a lot of changes for JavaScript development in this release. + +**Breaking Changes** + +A change like this comes with a few breaking changes: We deprecated some advanced configuration settings: `validate.scope`, `validate.baseUrl`, `validate.target`, `validate.module`, `validate.noLib`. We're providing support for `jsconfig.json` to offset these settings no longer being supported. + +**Support for ES6** + +A popular request since our launch has been support for ES6 (ECMAScript 6, the latest update of JavaScript targeting ratification in June 2015). You can expect VS Code to understand the new ES6 syntax elements and their semantics. + +Note that super-references in deriving object-literals is still on our plate; currently if you try this in VS Code you'll receive a faulty compile error, which you can suppress with the `_surpressSuperWithoutSuperTypeError: [true|false]` option. + +>**Tip:** A good overview of the new ES6 features can be found here: + +**Projects - jsconfig.json** + +You can create a JavaScript project by dropping in a `jsconfig.json` file. It's a subset of [tsconfig.json](https://github.com/Microsoft/TypeScript/wiki/tsconfig.json), and it allows you to define what files are part of a project, and what compiler options to use. +Same as in `tsconfig.json` if no "files" property is present in a `jsconfig.json`, we default to including all files in the containing directory and subdirectories. When a "files" property is specified, only those files are included. + +![jsonconfig.json](images/0_5_0/JsconfigJson.png) + +This means you don’t need to use `///` references anymore. As the project defines the file set, VS Code just knows what files and symbols are part of your project. As an example, you can just drop a new `.d.ts` file into your project folder and VS Code will pick it up automatically. + +>**Note:** In the Editor Options section, we discuss how you can hide derived files in the Explorer window, e.g. `*.js` files generated from `*.ts` sources. In the Debugging section, we discuss support for JavaScript Source Maps and minified/uglified JavaScript debugging. + +**Shebang coloring** + +We improved colorization for shebang `#!`, as shown in the first line here: + +![Shebang coloring](images/0_5_0/ShebangColoring.png) + +## Snippets + +VS Code launched with [snippet support](/docs/editor/userdefinedsnippets.md), and we've added some notable enhancements in this release. + +**User-defined snippets** + +To add your own code snippets, use the newly added User Snippet action available by **File** | **Preferences**. This action opens a language selection dialog. Selecting a language will open the snippets for the file language. Enter your snippets directly in the editor. + +>**Tip:** Changes are picked up on save (there's no need to restart VS Code). + +This is an example of a snippet file: + +``` +{ + "Node Require" : { + "prefix": "require", + "body": [ + "var ${module} = require('${module}');", + "$0" + ], + "description": "Node require statement" + } +} +``` + +Each property in the object represents a snippet. + +* `body` is what is inserted when the snippet is selected. +* `description` is shown as additional information. +* `prefix` is what IntelliSense will use as a label and to filter against. + +The body format follows the TextMate template syntax (https://manual.macromates.com/en/snippets), with the following constructs supported: + +* plain text +* placeholders with identifiers `${id: text}` +* simple tab placeholders `$0, $1, …` +* nested placeholders `${id1: some text ${id2: nested text} }` + +We have also added some more snippets out of the box for Dockerfiles, Python, and Rust. + +## Git + +We updated our Git support by delivering several of the most requested features. + +**Credential prompt** + +Many users have reported that the Git tools can be non-responsive. This is typically a result of the Git action being blocked by an authentication prompt. With this update, when Git requires credentials you will see a pop-up, prompting you to enter the required credentials. + +![Credential prompt](images/0_5_0/CredentialPrompt.png) + +>**Tip:** If you don’t want to always enter your credentials, consider using a [credential helper](https://help.github.com/articles/caching-your-github-password-in-git/). + +**Multiline commit** + +Previously, commit messages in VS Code supported only a single line of text. We now support multiple lines of text in your commit message. (Type `kbstyle(Ctrl+Enter)` to finish the commit message, or `kbstyle(Enter)` to add a new line to the message.) + +![Multiline commit message](images/0_5_0/MultilineCommit.png) + +**Multiple file selection** + +Multiple selection is now enabled in the Git view, meaning you can stage/unstage or commit multiple files at the same time. + +![Select multiple files](images/0_5_0/GitMultiSelect.gif) + +**Auto fetch control** + +There is now an action to enable/disable Git auto fetch in the dropdown menu of the Git view. This is handy if you don’t have a credential helper and don’t want to get prompted for authentication all the time. + +## Debugging + +Debugging is core to the workflow enabled by VS Code, and with this release we support several additional scenarios. + +**Improved launch.json generation** + +We are now consulting package.json for a main attribute when generating launch.json. The result is the generated launch.json is more precise. + +**Watch expressions** + +We added a new debug pane for watch expressions. You are able to add, rename or remove watch expressions from the Debug view. Based on the focused stack frame, watch expressions are reevaluated whenever the debug target has stopped. It is also possible to add an expression to watch using the editor context menu. + +![Watch expressions](images/0_5_0/WatchExpressions.png) + +**Ability to edit during debug** + +The workbench is no longer in read-only mode when debugging. +However, VS Code does not yet support 'hot code replacement', so edited code is not automatically picked up by the debugger +but a new 'Restart Session' action helps to improve the experience. + +**Improved Node breakpoint handling** + +Node does not parse source files completely on load, rather it delays parsing of closures (e.g. callbacks) until their code is first hit. As a consequence, breakpoints set on callbacks are sometimes not registered for the line requested but instead register for the next possible line in already-parsed code. To avoid confusion, we now show breakpoints at the location where node thinks the breakpoint is. In the breakpoint view, these breakpoints are shown with this notation: + +*request line* → *actual line* + +Here's an example: + +![Node breakpoints](images/0_5_0/NodeBreakpoints.png) + +This breakpoint validation occurs when a session starts and the breakpoints are registered with node, or when a session is already running and a new breakpoint is set. In this case, the breakpoint may "jump" to a different location. After node.js has parsed all the code (e.g,. by running through it), breakpoints can be easily re-applied to the requested locations with the Reapply button in the breakpoint view's header. This should make the breakpoints "jump back" to the requested location. + + +**Activate / deactivate breakpoints** + +You can now toggle the active breakpoints. + +![Toggle active breakpoints](images/0_5_0/ToggleActiveBPs.png) + +**JavaScript source maps** + +If generated (transpiled) JavaScript files do not live next to their source, you can help the VS Code debugger locate them by specifying the outDir directory in the launch configuration. Whenever you set a breakpoint in the original source, VS Code tries to find the generated source, and the associated source map, in the outDir directory. + +In-lined source maps (a source map where the content is stored as a data url instead of a separate file) are now supported, although in-lined source is not yet supported. + +**Minified debugging** + +Debugging minified/uglified JavaScript is now supported. + +## Other stuff + +**Output toggling** + +A new action was added that allows to toggle the output window. When output is not showing, it will just show output. But when output is showing, it will restore the previous editor you'd been using. This allows to quickly check the output and then quickly return to the work you did before. The action replaces the previous "Show Output" action, so by default the keybinding for output toggling is Ctrl+Shift+U (Cmd+Shift+U on Mac). + +**Auto-update enabled for OS X and Windows** + +With this update, future updates will be automatic for OS X and Windows users (we don't support auto-updates for Linux). If you want to opt out of auto-updates, see instructions [here](https://go.microsoft.com/fwlink/?LinkID=616397). + +**Proxy Support** + +Http requests for package/project/bower.json IntelliSense as well as fetching schemas and for Send-a-Smile now can go through a proxy server. + +To configure a proxy either: + +* Set the `http_proxy` and the `https_proxy` environment variables before starting VS Code. +* Set the `http.proxy` user setting. + +>**Note:** VS Code supports http and https proxies, but not SOCKS proxies. + +**Notable Bug Fixes** + +* [16480](https://code.visualstudio.com/issues/Detail/16480): Git push/pull not working +* [16782](https://code.visualstudio.com/issues/Detail/16782): Fonts Are Blurry +* [17223](https://code.visualstudio.com/issues/Detail/17223): SourceMap debugging doesn't work with inlined source map +* [17079](https://code.visualstudio.com/issues/Detail/17079): OS X Poor Scrolling in Explore Sidebar + + +For a list of currently known issues, see our [FAQ](/docs/supporting/faq.md). You can view or report new issues [here](/issues). diff --git a/release-notes/v0_7_0.md b/release-notes/v0_7_0.md new file mode 100644 index 0000000000000000000000000000000000000000..c059ad6719edcbe961f1b043580ccc4df500e598 --- /dev/null +++ b/release-notes/v0_7_0.md @@ -0,0 +1,172 @@ +--- +Order: +TOCTitle: August 2015 +PageTitle: Visual Studio Code 0.7.1 +MetaDescription: See what is new in Visual Studio Code 0.7.1 +--- +# August 2015 (0.7.1) + +Hi, + +It's time to update VS Code again :) This is a smaller update in terms of raw added features – but have no fear we are not slacking off - behind the scenes we are working hard to add plug-in support to VS Code. Paired with this release we have also made a number of updates to our documentation. + +Read on to find out what's new... + + +## Improved Documentation +With this release we updated almost all of our documentation to help you get more out of VS Code. + +We broke down the content into four sections: +* [Overview](/docs) - A quick summary of all the documentation including a video overview +* [Editor](/docs/editor/codebasics.md) - An introduction to VS Code itself from editing all the way to debugging and tasks +* [Languages](/docs/languages/overview.md) - Walkthroughs on how to get the best out of VS Code when using specific languages e.g. JavaScript + +![Updated docs for VS Code](images/0_7_0/docsUpdate.png) + +>**Tip:** You can search our site via the search box in the header. + +## Debugging + +### node.js: Large data stucture improvments +In previous versions of VS Code, debugging would stall (and timeout) when stepping through code that used large Arrays or Buffers. In this version the VS Code debugger treats large data structures (Arrays and Buffers) in a more scalable way and should no longer timeout. The same should be true for drilling into large data structures in the variables or watches view section. + +As a consequence, the debugger now renders the contents of Arrays and Buffers in chunks. + +![Chunked Arrays](images/0_7_0/DebugChunkedArrays.png) + +>**Note:** These improvements require version 0.12.x of node.js (these improvements are not yet supported for io.js). + + +### node.js: Stable breakpoints +For performance reasons node.js parses the functions inside JavaScript files lazily on first access. As a consequence, breakpoints don't work in source code that hasn't been seen (parsed) by node.js. + +Since this behavior is not ideal for debugging, VS Code now passes the `--nolazy` option to node.js automatically. This prevents the delayed parsing and ensures that breakpoints can be validated before running the code (so they should no longer 'jump'). + +>**Tip:** If you have to attach VS Code to an already running node process, be aware that this node.js runtime probably wasn't started with the `--nolazy` flag. + + +### Variable support in launch.json +VS Code now supports variables in the `launch.json` file in the same way as in `tasks.json` (see [Tasks](/docs/editor/tasks.md#variables-in-tasksjson)). + + +### Run to cursor +You can now run up to the cursor location with a new action included in the context menu. + + + +## Tasks +We did a significant review of the [Tasks documentation](/docs/editor/tasks.md) with this update and have included several examples of using tasks. + +We also now support automatic detection of tasks in a `gruntfile`. This works the same as our support for the Gulp and Jake task runners (see [Tasks](/docs/editor/tasks.md#autodetecting-gulp-grunt-and-jake-tasks)). + + + +## Markdown +We added a full overview of [how to use VS Code with Markdown files](/docs/languages/markdown.md). + +We now show you how to: +* leverage built-in snippets +* configure preview with custom CSS +* use Auto Save for live updates +* use tasks to compile to HTML + +## JavaScript +In our [JavaScript documentation](/docs/languages/javascript.md) we've added topics covering: +* JavaScript projects with `jsconfig.json` +* `ES6` support +* Configuring linters such as `JSHint` and `ESLint` +* Rich Editing Support +* IntelliSense + +We also updated the quick fix code action. *Add /// reference for typing file* was renamed because `///` references are no longer needed to get IntelliSense from `.d.ts` files. The action is now called *Download type definition for some typing file* and it downloads the `.d.ts` file only. + +We added the ability to exclude files and folders from a project via the addition of an `exclude` property in the `jsconfig.json`. This is useful when you want to exclude folders with generated JavaScript code. + +```json +{ + "compilerOptions": { + "target": "ES6" + }, + "exclude": [ + "node_modules" + ] +} +``` + +Finally, one key bug we fixed in this update was unlocking the ability to work with Ember.js/ES6/AMD projects - previously VS Code would crash with these large projects. + + +## HTML +We improved our HTML formatter in this release and updated the [HTML documentation](/docs/languages/html.md). + + +## JSON +We improved the JSON formatter, specifically formatting with comments and formatting ranges. + +In the [JSON documentation](/docs/languages/json.md) we now include examples of: +* Working with JSON comments +* IntelliSense and Schema validation +* Quick navigation +* Hovers and Toggle Values +* Configuring JSON Schemas + + +## CSS, Less and Sass +We updated our [CSS, Less and Sass documentation](/docs/languages/css.md) to provide examples of how to work with CSS in VS Code. + +This includes sections on: +* CSS IntelliSense +* Emmet Snippet support +* Syntax highlighting and Color preview +* Goto symbol & Hover support +* Goto declaration & Find references +* Using tasks to transpile Sass and Less into CSS +* Customizing CSS settings + + +## PHP +We added a set of common snippets for PHP. To access these hit `kb(editor.action.triggerSuggest)` to get a context specific list. + +![PHP Snipets](images/0_7_0/PHPSnip.png) + +## C# +We have moved to the latest OmniSharp version 1.1.0. + +We also added in early support for quick fixes (aka. lightbulbs) via Roslyn and NRefactory. + +Quick fixes are automatically computed when you put the cursor onto a marker; they can also be requested by pressing `kb(editor.action.quickFix)`. + +![Quick Fix - Marker](images/0_7_0/QuickFixOnMarker.png) + + +In the image below you can see the prompt to extract a method from the current selection: + +![Quick Fix - Selection](images/0_7_0/QuickFixOnSelection.png) + + +## Dockerfile +We added a new document that covers our [Docker](/docs/azure/docker.md) support. + +Our Docker support includes: +* Dockerfile - Hovering over instructions +* Docker-compose.yml - Hovering over keys and images, rule completion, image name completion + + +## Swift +We added syntax coloring and a set of common snippets. + + +## Groovy +We added syntax coloring and a set of common snippets. + + +## Notable Bug Fixes +As always we fixed many issues. + +Here are a few of the notable ones from the public bug tracker: + +* [17915](/Issues/Detail/17915): VS Code crashes with large emberjs/es6/amd project +* [17427](/Issues/Detail/17427): Git cannot be found if installed into a non-default location +* [17947](/Issues/Detail/17947): Open with encoding Windows 866 doesn't work +* [18094](/Issues/Detail/18094): Wrong "duplicate identifier" error in node files when using "exports"* + diff --git a/release-notes/v0_8_0.md b/release-notes/v0_8_0.md new file mode 100644 index 0000000000000000000000000000000000000000..51b043d88768c54ec24d71c46821f375fa8fb840 --- /dev/null +++ b/release-notes/v0_8_0.md @@ -0,0 +1,101 @@ +--- +Order: +TOCTitle: September 2015 +PageTitle: Visual Studio Code 0.8.0 +MetaDescription: See what is new in Visual Studio Code 0.8.0 +--- +# September 2015 (0.8.0) + +Hi, + +It’s that time again – our September update is ready for VS Code. + +## Important Updates and Breaking Changes +Before we get into all of the exciting new stuff, there are a couple of key changes with this update that we don't want you to miss. + + +### New Windows Setup +We adopted a new installation and update framework for Windows based on [Inno Setup](http://www.jrsoftware.org/isinfo.php). +This fixes many Windows integration issues and streamlines the update story. + +>**Note:** You will see a two stage update as a result of the change to the new installer. First to version 0.7.20 to bootstrap the new installer and then to the 0.8.0 release version. The new installer will prompt you during installation. Continue through the setup dialog to install VS Code 0.8.0. + +>**Tip:** You will need to close any currently open command windows to pick up the new PATH setting. + +### Renamed VS Code Settings Folder +We renamed the top level `.settings` folder to `.vscode` to make it clear that this folder contains VS Code specific configurations and to avoid conflicts with other IDEs who may also use a folder named `.settings` (e.g. Eclipse). + +When you update to version 0.8.0, VS Code will rename the folder to the new name and inform you if you had any files in a `.settings` folder. + + +## Additional Themes +VS Code is now able to apply TextMate syntax color themes (.tmTheme). We picked some themes from (https://colorsublime.github.io/) and made them available under `File | Preferences | Color Theme`. In one of the next releases, users will be able to extend this list with their own favorite themes. + +Open the Color Theme picker with `File | Preferences | Color Theme` and use the up and down keys to change the selection and preview the themes. + +![Color Themes](images/0_8_0/colorthemes.gif) + + +## Debugging - No Mono Dependency for Node +We have ported the implementation of the Node.js debugging support from C#/Mono to TypeScript/Node.js, eliminating our Mono dependency for debugging Node.js applications on macOS and Linux. + + +## Debugging - Debug Console +In this release, we included a preview of the Debug Console for easy evaluation of expressions. The Debug Console can be opened using the `Open Console` action at the top of the Debug view or using the `Debug: Open Console` action in the Command Palette. + +![Debug Console](images/0_8_0/debugconsole.png) + + +## Languages - JavaScript Linting as you Type +VS Code now provides support for [ESlint](http://eslint.org/) and [JSHint](http://jshint.com/). If enabled, the JavaScript code is validated as you type and reported problems can be navigated to and fixed inside VS Code. + +To enable one of the linters do the following: + +* Install the corresponding linter globally or inside the workspace folder that contains the JavaScript code to be validated. For example using the command lines: `npm install eslint --save-dev` or `npm install jshint --save-dev`, respectively. +* Enable eslint or jshint via the corresponding VS Code settings `"eslint.enable": true` or `"jshint.enable": true`, respectively. +* Optionally disable VS Code's built-in JavaScript validation via the setting `"javascript.validate.enable": false`. + +Try it out by opening a JavaScript file and adding a problem that should be detected by the enabled linter. VS Code shows problems inside the editor and in the status bar. + +## Languages - TypeScript 1.6 Support + +>**Note:** At this time, TypeScript 1.6 should be considered experimental so proceed at your own risk. :) + +VS Code uses TypeScript 1.5 in the box. If you want to use a newer version of TypeScript, you can define the `typescript.tsdk` setting. The value of this setting is the absolute path to the `lib` folder of a TypeScript installation. This folder contains the file `tsserver.js` and the corresponding `lib.*.d.ts` files. Refer to this [blog post](https://devblogs.microsoft.com/typescript/introducing-typescript-npm-nightlies-2) for how to install the nightly builds of TypeScript. + +## Languages - TSX +We now support colorizing TSX (TypeScript JSX) files. To get full language support for TSX files, you need to install the latest TypeScript 1.6 version and configure VS Code to use it with the `typescript.tsdk` setting, as described above. + +To learn more about how to use TSX with TypeScript refer to the [TypeScript TSX Wiki page](https://github.com/Microsoft/TypeScript/wiki/JSX). + + +## Languages - JSX Colorization +We now support colorizing JSX files. + + +## Languages - C# on Omnisharp 1.1.1 +We have moved to the OmniSharp version 1.1.1 [(OmniSharp releases)](https://github.com/OmniSharp/omnisharp-roslyn/releases). This version of OmniSharp will happily work with DNX Beta7 but note that on Linux and Mac there is not yet support for using [CoreCLR](https://github.com/OmniSharp/omnisharp-roslyn/issues/294) as a development platform. + + + +## Git - Undo Last Commit +There is a new `Undo Last Commit` action which will let you undo your previous commit, keeping the changes in the working folder. + + + +## Tasks - echoCommand Property +A new property `echoCommand` has been added to the global and task specific sections of the `tasks.json` file. If set to `true`, the executed command is echoed to the task's output view. This is useful when you are configuring tasks and you want to see the full command VS Code is running. + + + +## Notable Bug Fixes + +As always we fixed many issues. + +Here are a few of the notable ones from the public bug tracker: + +* [18617](/Issues/Detail/18617): C# IntelliSense suggestions only come up after error checking, making them slow over time +* [17259](/Issues/Detail/17259): Cannot control installation location +* [18603](/Issues/Detail/18603): Duplicate icon on Windows 10 +* [17159](/Issues/Detail/17159): Cannot open a file with spaces in its name from command line + diff --git a/release-notes/v0_9_0.md b/release-notes/v0_9_0.md new file mode 100644 index 0000000000000000000000000000000000000000..74d8a406841c01815f506d16a45fec2bbdb28e6f --- /dev/null +++ b/release-notes/v0_9_0.md @@ -0,0 +1,159 @@ +--- +Order: +TOCTitle: October 2015 +PageTitle: Visual Studio Code 0.9.1 +MetaDescription: See what is new in Visual Studio Code 0.9.1 +--- + +# October 2015 (0.9.1) + +Hi, + +It’s that time again – our October update is ready for VS Code. + +## Persistent (update to update) location for Customizations +Previously we did not have a location we respected across updates. It's true that we did have a location for user settings but as we get closer to our final update story we added a new location. In the future, we will (gracefully) move all user settings here. + +The new location is `.vscode/extensions` under your user directory. + +Depending on your platform, this folder is located here: +* **Windows** `%USERPROFILE%\.vscode\extensions` +* **Mac** `$HOME/.vscode/extensions` +* **Linux** `$HOME/.vscode/extensions` + +As this location is under your user directory, the content is persisted across VS Code updates. This is just the start and we plan to use this location more in future updates. + +## Yo Code - Streamlined Customizations for VS Code +We re-purposed the Yeoman generator we used for the VS Code Node.js sample `generator-code` and we are now using this to make creating common customizations easier. + +In this release of the generator, we have the ability to create two common customizations: + +1. Additional color themes +2. Syntax highlighters/bracket matchers + +In the future, we'll add other options for rich customization of VS Code. + +If you have a TextMate color theme (.tmTheme) or a TextMate language specification (.tmLanguage), you can bring them into VS Code using the 'code' Yeoman generator. + +Install and run the code Yeoman generator as follows: +1. `npm install -g yo` +2. `npm install -g generator-code` +3. `yo code` + +![yo code](images/0_9_0/yocode.png) + +The Yeoman generator will walk you through creating your customization prompting for the required information. Once the generator is finished, copy the generator's output folder to a new folder under the `.vscode/extensions` folder and restart VS Code to use the new features. + +In the future you will be able to publish these customizations to an external gallery to share them with the community. + +>**Tip:** If you want to share your customization with others in the meantime, you can simply send them a copy of the output from the generator and ask them to add it under their `.vscode/extensions` folder. + +## Customization - Adding Language Colorization & Bracket Matching +Using the 'code' Yeoman generator you can add TextMate language specification files (.tmLanguage) to your VS Code installation to get syntax highlighting and bracket matching. + +A good place to look for existing TextMate .tmLanguage files is on GitHub. Search for a TextMate bundle for the language you are interested in and then navigate to the `Syntaxes` folder. The 'code' Yeoman generator can handle either .tmLanguage or .plist files. When prompted for the URL or file location, pass the raw path to the .tmLanguage file e.g. https://raw.githubusercontent.com/textmate/ant.tmbundle/master/Syntaxes/Ant.tmLanguage. + +![yo code language](images/0_9_0/yocodelanguage.png) + +The generator will prompt you for other information such as a unique name (this should be unique to avoid clashing with other customizations) and the language name, aliases and file extensions. + +When the generator is finished, copy the complete output folder to a new folder under `.vscode/extensions`. When you restart VS Code, your new language will be visible in the language specifier dropdown and you'll get full colorization and bracket/tag matching for files matching the language's file extension. + +![ant language](images/0_9_0/antlanguage.png) + +## Customization - Adding Themes +You can also add new TextMate theme files (.tmTheme) to your VS Code installation. + +[ColorSublime](https://colorsublime.github.io) has hundreds of existing TextMate themes to choose from. Pick a theme you like and copy the Download link to use in the Yeoman generator. The 'code' generator will prompt you for the URL or file location of the .tmTheme file, the theme name as well as other information for the theme. + +![yo code theme](images/0_9_0/yocodetheme.png) + +Copy the generated theme folder to a new folder under `.vscode/extensions` and restart VS Code. + +Open the Color Theme picker theme with `File | Preferences | Color Theme` and you can see your theme in the dropdown. Arrow up and down to see a live preview of your theme. + +![my theme](images/0_9_0/mytheme.png) + +While building this, the VS Code team contributed a [Pull Request](https://github.com/atom/node-oniguruma/pull/40) to [node-oniguruma](https://github.com/atom/node-oniguruma) that results in a nice performance improvement when colorizing/tokenizing. Both the Atom and VS Code IDEs profit from this improvement. + +## Debugging - Performance +We improved stepping performance by loading the scopes and variables of stack frames lazily. This improvement is based on a protocol change that affects all debug adapters. + +## Debugging - Pre-Launch Task +In a project's launch configurations (launch.json), you can now use the `preLaunchTask` attribute to specify a task to run before a debug session starts. + +For example, with this option you could make sure that your project is built before it is launched in the debugger. If the task results in errors, an error message warns you and you can decide to either fix the errors or continue launching the debugger. + +## Debugging - Debug Console +We have made many improvements to the Debug Console: +* Text selection is now supported +* Better colors for improved visibility +* Richer context menus +* Expansion of elements is preserved between sessions + +![Debug Console](images/0_9_0/debugconsole.png) + +## Languages - C# +The status of the OmniSharp server is now using a new language status indicator in the lower right corner. This makes it much easier to see the context OmniSharp is running under and any issues. + +![Language Status indicator](images/0_9_0/lang-status.png) + +## Languages - TypeScript +We now ship with TypeScript 1.6.2. You can learn more about the latest release of TypeScript at [Announcing TypeScript 1.6](https://devblogs.microsoft.com/typescript/announcing-typescript-1-6-2). + +We simplified defining a task to run the TypeScript compiler in watch mode. +You can now configure the `watch` property in the `tsconfig.json` and then define a task as follows: + +``` +{ + "version": "0.1.0", + "command": "tsc", + "isShellCommand": true, + // define the task to be a watching task + "isWatching": true, + // use the standard tsc in watch mode problem matcher to find compile problems in the output. + "problemMatcher": "$tsc-watch" +} +``` + +## Languages - Markdown Preview +Markdown preview was improved so that embedded code stands out more clearly and the overall font sizes and spacing were optimized. In addition +there is a new action to quickly open the Markdown preview to the side (Markdown: Open Preview to the Side). + +![open preview side](images/0_9_0/openpreviewside.png) + +## Runtimes - Unity + +We've added colorization for Unity shader files. + +![unity shader colorization](images/0_9_0/unityshadercolorization.png) + + +## Files - New Settings + +We added two new configuration options to control how files open and folders reopen between sessions. + +The `window.openFilesInNewWindow` setting controls if files should open in a new window instead of reusing an existing VS Code instance. By default, VS Code will +open a new window, e.g. when you double-click on a file outside VS Code or open a file from the command line. Set this to `false` to reuse the last +active instance of VS Code and open files in there. + +The `window.reopenFolders` setting tells VS Code how to restore the opened windows of your previous session. By default, VS Code will +reopen the last opened folder you worked on (setting: `one`). Change this setting to `none` to never reopen any folders and always start with an +empty VS Code instance. Change it to `all` to restore all folders you worked on. This will reopen all the windows with folders of your previous session. + +## Notable Bug Fixes + +As always we fixed many issues. + +Here are a few of the notable ones from the public bug tracker: + +* [18998](https://code.visualstudio.com/Issues/Detail/18998): newly added files not honored by tsconfig.json +* [18692](https://code.visualstudio.com/Issues/Detail/18692): Changes to tsconfig.json not updated immediately +* [19239](https://code.visualstudio.com/Issues/Detail/19239): Detaching from Unity Results in a Unity Crash + +Other issues we've fixed: + +* JSON schemas support external references. +* The CSS tooling now supports CSS3 identifier escaping. +* Node.js Debugger: In 0.9.0, we focused on fixing the problems that resulted from the introduction of a new implementation of the Node.js debugger in VS Code 0.8.0. +You should no longer see empty CALL STACK, VARIABLES and WATCH views. diff --git a/release-notes/v1_10.md b/release-notes/v1_10.md new file mode 100644 index 0000000000000000000000000000000000000000..f50686603c39adc87832a1a66fd1ac843a79090a --- /dev/null +++ b/release-notes/v1_10.md @@ -0,0 +1,624 @@ +--- +Order: 19 +TOCTitle: February 2017 +PageTitle: Visual Studio Code February 2017 +MetaDescription: See what is new in the Visual Studio Code February 2017 Release (1.10) +MetaSocialImage: 1_10/release-highlights.png +--- +# February 2017 (version 1.10) + +**Update 1.10.2**: Adds the 1.10 translations and addresses a handful of [issues](https://github.com/Microsoft/vscode/milestone/38?closed=1). + +Downloads: [Windows](https://vscode-update.azurewebsites.net/1.10.2/win32/stable) | [Mac](https://vscode-update.azurewebsites.net/1.10.2/darwin/stable) | Linux 64-bit: [.tar.gz](https://vscode-update.azurewebsites.net/1.10.2/linux-x64/stable) [.deb](https://vscode-update.azurewebsites.net/1.10.2/linux-deb-x64/stable) [.rpm](https://vscode-update.azurewebsites.net/1.10.2/linux-rpm-x64/stable) | Linux 32-bit: [.tar.gz](https://vscode-update.azurewebsites.net/1.10.2/linux-ia32/stable) [.deb](https://vscode-update.azurewebsites.net/1.10.2/linux-deb-ia32/stable) [.rpm](https://vscode-update.azurewebsites.net/1.10.2/linux-rpm-ia32/stable) + +--- + +## February Release Summary + +Welcome to the February 2017 release of Visual Studio Code. There are a number of significant updates in this version that we hope you will like, some of the key highlights include: + +* **[Preview: Minimap](#preview-minimap)** - Get a 10,000 foot view of your code with Minimap. +* **[Preview: Drag and Drop in the editor](#preview-drag-and-drop-selected-text)** - Easily drag and drop text around the editor. +* **[Copy text with formatting](#copy-with-syntax-highlighting)** - Copy code examples with full syntax highlighting. +* **[Auto generate JSDoc](#auto-jsdoc-comments)** - Simply type `/**` to generate JSDoc comments for your functions. +* **[File Explorer key bindings](#configurable-explorer-key-bindings)** - You can now create shortcuts for the Explorer and other list/tree UI. +* **[Official Linux repositories](#official-signed-repositories-for-linux)** - VS Code supports auto-updating packages on Linux. +* **[Improved Exception view](#improved-exception-experience)** - Easily view exception details in the debugger. +* **[Column breakpoints](#column-breakpoints)** - Set multiple breakpoints on the same line of source code. +* **[Links in the Terminal](#links-in-the-terminal)** - Integrated Terminal output links streamline the workflow between editor and commands. +* **[Keybinding support for tasks](#key-bindings-per-task)** - Assign keyboard shortcuts to commonly used tasks. +* **[HTML DOM navigation](#html)** - Quickly navigate to DOM elements by id and class name. +* **[Language specific default settings](#go-make-yaml-markdown)** - Appropriate default settings for Go, Make, YAML and Markdown. + +The release notes are arranged in the following sections related to VS Code focus areas. Here are some further updates: + +* **[Editor](#editor)** - Word wrap settings simplification, manually trigger Save actions, new cursor styles. +* **[Workbench](#workbench)** - Configurable window title, run either selected text or entire file from the Integrated Terminal. +* **[Languages](#languages)** - TypeScript 2.2, disable color preview decorators, better link navigation in Markdown. +* **[Debugging](#debugging)** - Launch debugger using just the keyboard, new variable syntax. +* **[Tasks](#task-support)** - Run tasks in separate terminals, new ${lineNumber} variable. +* **[Extension Authoring](#extension-authoring)** - Pluggable SCM provider, Modal message dialogs, provide language specific settings. + +>**Tip:** Want to see new features as soon as possible? You can download the nightly Insiders [build](https://code.visualstudio.com/insiders) and try the latest updates as soon as they are available. + +## Editor + +### Preview: Minimap + +A Minimap gives you a high level overview of your source code which is very useful for quick navigation and code understanding. To enable VS Code's Minimap, set `"editor.minimap.enabled": true` to turn on the rendering of a Minimap for the current file. + +![Minimap](images/1_10/minimap.png) + +The screenshot above is on a Surface Book (high DPI display). Based on the `devicePixelRatio` (for example, regular or retina/high DPI displays), the Minimap will render characters either at 4x2 pixels or at 2x1 pixels. + +For those that would prefer a more schematic representation for the current file, there is `editor.minimap.renderCharacters` that can be set to `false` to render blocks instead of characters in the Minimap. + +Here it is on a regular display: + +![Minimap Blocks](images/1_10/minimap-blocks-scroll.gif) + +This milestone we have focused on rendering the characters in a fast, incremental way (we reuse as many pixels as possible from the previous frame when rendering a new frame). We plan to add more useful information to the Minimap in the future, for example current selection, find matches, Git diff annotations, etc. + +### Preview: Drag and Drop selected text + +You can now use the mouse to drag and drop selected text inside the editor. This feature is disabled by default and you can turn it on by set `editor.dragAndDrop` to `true`. + +![Drag and drop](images/1_10/drag-and-drop.gif) + +Please note we don't support drag-and-drop across editors or across different applications at the moment. + +### Copy with syntax highlighting + +You can now copy selected text to the Clipboard with syntax highlighting. It can be very useful when you paste the content into another application, for example, Outlook, and the content pasted into the application still has the correct formatting and colorization. + +Technically, we add a new entry for HTML content into the Clipboard so even if the target application doesn't support pasting rich text, the pasting will still work. + +![Copy with syntax highlighting](images/1_10/copy-with-syntax-highlighting.gif) + +Copying plain text to the Clipboard is easy and straight-forward but copying text with syntax highlighting has to pay the price of rendering based on the Theme you are using, so in order to make sure this feature doesn't slow down VS Code noticeably, we turn it off if you are copying a selection which contains more than 65536 characters. + +If Copy and Paste with correct format and colors is your top priority, so you can always manually run the new command `editor.action.clipboardCopyWithSyntaxHighlightingAction` or even bind it to `kbstyle(ctrl/cmd+c)` so you don't need to worry if the selection length reaches the limit. + +### Word wrap settings redesign + +In VS Code 1.9, we've changed the **Toggle Word Wrap** action to persist to User settings. The change was received with mixed feelings by our community, so for VS Code 1.10 we have rolled back that change and the action will only temporarily affect the current focused editor. + +The change also started a healthy discussion around the difficulty of configuring the editor's wrapping behavior. We therefore decided to deprecate `editor.wrappingColumn` (with its -1, 0, >0 cases) in favor of `editor.wordWrap`. + +Here are the new word wrap options: + +* `editor.wordWrap: "off"` - Lines will never wrap. +* `editor.wordWrap: "on"` - Lines will wrap at viewport width. +* `editor.wordWrap: "wordWrapColumn"` - Lines will wrap at the value of `editor.wordWrapColumn`. +* `editor.wordWrap: "bounded"` - Lines will wrap at the minimum of viewport width and the value of `editor.wordWrapColumn`. + +We also changed the default and now VS Code ships with `editor.wordWrap: "off"`. + +In this release, we added support for [language specific default settings](#language-specific-editor-settings) and we now turn on word wrap by default for Markdown files. + +### Manually trigger save actions + +You can now save an editor via `kb(workbench.action.files.save)` even if the file is not dirty and extensions which perform actions on save will be triggered. This allows you to trigger Format on Save even if the file is not dirty. + +### New cursor styles + +Thanks to [PR #14237](https://github.com/Microsoft/vscode/pull/14237), there are three more cursor styles available: `'line-thin'`, `'underline-thin'` and `'block-outline'`. + +## Workbench + + +### Configurable Explorer key bindings + +By popular demand, you can now configure the key bindings for most of the commands in the File Explorer and OPEN EDITORS view. + +The following commands could already be assigned prior to version 1.10 in the File Explorer: + +* `explorer.newFile` - Create a new file +* `explorer.newFolder`- Create a new folder + +New commands that work in both the File Explorer and OPEN EDITORS view + +* `explorer.openToSide` - Open to the side +* `copyFilePath` - Copy path of file/folder +* `revealFileInOS` - Reveal file in OS + +New commands that only work in the File Explorer: + +* `filesExplorer.copy` - Copy a file from the File Explorer +* `filesExplorer.paste` - Paste a file that was copied from the File Explorer +* `renameFile` - Rename a file/folder in the File Explorer +* `moveFileToTrash` - Move a file/folder to trash from the File Explorer +* `deleteFile` - Bypass trash and delete a file/folder from the File Explorer +* `filesExplorer.findInFolder` - Find inside a folder from the File Explorer + +In addition to these commands, the following contexts are introduced for key bindings: + +* `filesExplorerFocus` - Keyboard focus is inside the File Explorer +* `openEditorsFocus` - Keyboard focus is inside the OPEN EDITORS view +* `explorerViewletFocus` - Keyboard focus is in either the File Explorer or OPEN EDITORS view + +### Configurable tree/list key bindings + +We introduced new commands (see below) to make working with trees and lists UI elements in VS Code more configurable for keyboard centric users. + +Here is a list of new commands that will work in every tree and list: + +|Command|Keyboard shortcut| +|---|---| +|`list.focusUp`|`kbstyle(Up Arrow)` (additionally on macOS: `kbstyle(Ctrl+P)`)| +|`list.focusDown`|`kbstyle(Down Arrow)` (additionally on macOS: `kbstyle(Ctrl+N)`)| +|`list.focusFirst`|`kbstyle(Home)`| +|`list.focusLast`|`kbstyle(End)`| +|`list.focusPageDown`|`kbstyle(PageDown)`| +|`list.focusPageUp`|`kbstyle(PageUp)`| +|`list.collapse`|`kbstyle(Left Arrow)` (additionally on macOS: `kbstyle(Cmd+Up Arrow)`)| +|`list.expand`|`kbstyle(Right Arrow)`| +|`list.clear`|`kbstyle(Escape)`| +|`list.select`|`kbstyle(Enter)` (additionally on macOS: `kbstyle(Cmd+Enter)`)| +|`list.toggleExpand`|`kbstyle(Space)`| + +With these new commands, we now consistently support `kbstyle(Ctrl+P)` and `kbstyle(Ctrl+N)` to navigate up and down in trees and lists on macOS. + +For example, on macOS to change the command to open from the File Explorer to be `kbstyle(Enter)` (which normally brings you into rename mode), configure: + +```json +{ + "key": "enter", + "command": "list.select", + "when": "filesExplorerFocus" +} +``` + +### Configurable window title + +We introduced a new setting `window.title` that can be used to change the window title based on the active editor opened. + +You can compose the title with the following variables (shown here for `/Users/Development/myProject/myFolder/myFile.txt`): + +* `${activeEditorLong}` - /Users/Development/myProject/myFolder/myFile.txt +* `${activeEditorMedium}` - myFolder/myFile.txt +* `${activeEditorShort}` - myFile.txt +* `${rootName}` - myProject +* `${rootPath}` - /Users/Development/myProject +* `${appName}` - Visual Studio Code +* `${dirty}` - a dirty indicator if the active editor is dirty +* `${separator}` - a conditional separator (" - ") that only shows when surrounded by variables with values + +The `window.title` has the following defaults: + +* Windows/Linux: `${dirty}${activeEditorShort}${separator}${rootName}${separator}${appName}` +* macOS: `${activeEditorShort}${separator}${rootName}` + +>**Note:** We no longer support `window.showFullPath` in favor of the `window.title` setting. The variable `${activeEditorLong}` will give you the full path. + +### Restore Zen Mode + +Per [user request](https://github.com/Microsoft/vscode/issues/19431), we have added a `zenMode.restore` setting to control if a window should restore to Zen Mode if it was exited in Zen Mode. + +### Theme configurations in settings + +New settings have been added that define the currently active Color and File Icon theme: + +```json +{ + // Specifies the color theme used in the workbench. + "workbench.colorTheme": "Default Dark+", + + // Specifies the icon theme used in the workbench. + "workbench.iconTheme": null +} +``` + +By placing the options in the workspace settings, you can now have a different theme per workspace. These used to be stored in a separate location but now they are in your settings files. + +To change a theme, you can still use the theme selection dialog in the **Preferences** menu with the **Preferences: Color Theme** and **Preferences: File Icon Theme** commands. + +### Links in the terminal + +The terminal now creates links for URLs and text that looks like a path. These links will either be opened in a browser or the editor when triggered respectively. + +![terminal link](images/1_10/terminal-link.png) + +### Run in terminal commands + +In previous releases, there was the single command `workbench.action.terminal.runSelectedText` which sent text to the terminal. This would send either the selection if there was one, or the entire file if not. This caused some issues as users would accidentally run entire files when they were expecting to run the current *line* if there was no selection. Running a file would also not work in some shells as the shell would interpret the text in chunks, not as a whole. To improve these scenarios, there are now two commands with distinct behaviors: + +- `workbench.action.terminal.runSelectedText`: Sends the selection if there is one to the terminal, otherwise sends the current line. +- `workbench.action.terminal.runActiveFile`: Sends the *file path* of the active file to the terminal (in most shells this will execute the file). + +### Display chord key bindings in menus + +In previous releases, you might have noticed that a menu entry would not show a keyboard shortcut even though you had a key binding assigned. The reason was that some key bindings (for example multiple key chords) cannot be displayed as keyboard shortcuts in menus (including context menus). + +As a workaround, we now show those key bindings as part of the menu label: + +![menu](images/1_10/menu.png) + +### Search results count + +We now show the total number of files and matches for a search in the Search View. + +![Search results count](images/1_10/search-results-count.png) + +### Improving search speed going forward + +We've been looking into how to make our file search even faster. We explored two alternatives: [Silver Searcher](https://github.com/ggreer/the_silver_searcher) and [ripgrep](https://github.com/BurntSushi/ripgrep). If your are interested in our findings, have a look at our [write-up](https://github.com/Microsoft/vscode/issues/19983#issuecomment-282581996). It's a good read. + +## Languages + +### TypeScript + +VS Code now ships with [TypeScript 2.2](https://devblogs.microsoft.com/typescript/announcing-typescript-2-2/). This release includes a number of [new language features](https://github.com/Microsoft/TypeScript/wiki/What's-new-in-TypeScript#typescript-22), bug fixes, and other enhancements. + +TypeScript 2.2 also brings support for a number of new quick fixes, including: + +* Add missing import +* Add missing property +* Add forgotten this to variable +* Remove unused declaration +* Implement interface or abstract class + +### Auto JSDoc comments + +VS Code will now provide a [JSDoc](http://usejsdoc.org) comment template for JavaScript and TypeScript functions when you type `/**`: + +![JSDoc autofill](images/1_10/jsdoc-autofill.gif) + +### HTML + +Document symbols are now available also for HTML, allowing you to quickly navigate to DOM nodes by id and class name. + +Press `kb(workbench.action.gotoSymbol)` to bring up the symbol in file. + +![HTML document symbols](images/1_10/html-document-symbols.png) + +Thanks to [Cody Hoover](https://github.com/hoovercj) for the contribution. + +### CSS + +The CSS, LESS and SCSS color preview decorators can now be disabled in the settings: + +```json + "css.colorDecorators.enable": true, + "scss.colorDecorators.enable": true, + "less.colorDecorators.enable": true +``` + +### Jade + +Jade is now known as [Pug](https://github.com/pugjs/pug/issues/2184). Nothing has changed but the language label. The language id is still `jade` and the `.jade` file extension is still served. + +### Vue + +While [Vue.js](https://vuejs.org) files may look like HTML files, they are much more than that. For that reason, the `.vue` file extension is no longer associated with HTML by default. However we do recommend you use a Vue.js specific extension for language support and the [vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur) extension is a good choice. + +### Go, Make, YAML, Markdown + +These languages are now using the new support for default configuration settings per language (see Default Language specific editor settings below). For Go, Make, and YAML, the default settings configure `kbstyle(Tab)` behavior as defined by these languages. For Markdown, the default enables word wrapping and disables quick suggestions. + +### Fragment link navigation for Markdown + +Links to Markdown files that include a fragment will now try to open the file at the corresponding header: + +```markdown +* [Section](#header) +* [Another file](./other_file.md#header) + +# Header +... +``` + +This allows quickly navigating documentation directly within the VS Code editor. + +## Debugging + +### Column breakpoints + +As per [popular request](https://github.com/Microsoft/vscode/issues/14784), we now support setting breakpoints on an editor column. +This helps debugging code that contains multiple statements on a single line which typically occurs with heavily chained promises or minified source. +A column breakpoint can be set using `kb(editor.debug.action.toggleInlineBreakpoint)` or via the context menu during a debug session. + +![column](images/1_10/column-breakpoints.gif) + +**Note**: A debug extension backend will adjust the location of breakpoints to 'possible' locations. This might cause breakpoints to move when starting a debug session or when setting a column breakpoint while a session is active. + +### Improved Exception experience + +To improve the visibility of exceptions as they occur during debugging, we now show the exception directly in the editor with a peek UI: + +![launch](images/1_10/exception-widget.png) + +[This issue](https://github.com/OmniSharp/omnisharp-vscode/issues/1007) was raised because sometimes users were not aware that an exception was raised (especially in library code). Another motivation for the introduction of the peek UI was to make it easy to show many more exception details. + +### Ability to select and start a launch using keyboard + +The option to launch debug configurations using just the keyboard (no mouse gesture necessary) was added, as per [this request](https://github.com/Microsoft/vscode/issues/16613). It works similarly to running tasks, with an ability to launch a debugging session from the **Command Palette**. The keyword `'debug '` or the command **Debug: Select and Start Debugging** from the **Command Palette** is used to select and launch a configuration from `launch.json`. + +![launch](images/1_10/launch-keyboard.gif) + +### New variable syntax + +Starting with this release, we now support the colon character ':' as a prefix separator in variable names (and we have deprecated the '.'). With this change, the new (and preferred) syntax for 'env', 'command', and 'config' variables becomes `${prefix:id}`. + +This makes command variables (where the command ID itself uses '.') much more readable: + +```json +"processID": "${command:extension.node-debug.pickProcess}" +``` + +### Precondition based on debugger type + +It is now possible to have a precondition based on the current debug type. Preconditions can be used when defining keyboard shortcuts or when registering new commands as an extension. + +Here's an example of a shortcut that will only be enabled while you are debugging with `type` 'node': + +```json +{ "key": "f6", "command": "workbench.action.debug.continue", "when": "debugType == 'node'" } +``` + +### Debug views sizes + +We have fine-tuned the default sizes of Debug views. Also once the size is changed by the user, we preserve it across different VS Code sessions. + +## Node Debugging + +### Node2 transitioning + +In this milestone, we've started to fold the two node debuggers ('node' and 'node2') into a single node debugging experience (behind the debug type 'node'). The goal of this is to detect the supported debugging protocol(s) of the targeted Node.js runtime automatically and to select the best debugger implementation based on that protocol. We call the [new protocol](https://developer.chrome.com/devtools/docs/debugger-protocol) 'inspector' and the (now obsolete) v8-debugger protocol 'legacy'. + +Starting with this release, we recommend that you only use the 'node' debug type and we've deprecated the 'node2' type ('node2' is still available but its use in launch configurations will be flagged with a deprecation warning). + +Since we still want to give you control over what debugger implementation to use, we've introduced a new attribute `protocol` with the following values: + +- **`auto`**: tries to automatically detect the protocol used by the targeted runtime. For configurations of request type `launch` and if no `runtimeExecutable` is specified, we try to determine the version by running Node.js from the PATH with an `--version` argument. If the version is >= 6.9, the new 'inspector' protocol is used. For configurations of request type 'attach', we try to connect with the new protocol and if that works, we use the 'inspector' protocol. We only switch to the new inspector protocol for versions >= 6.9 because of problems in earlier versions. +- **`inspector`**: forces the node debugger to use the 'inspector' protocol based implementation (aka 'node2'). This is supported by Node.js versions >= 6.3, but not (yet) by Electron. +- **`legacy`**: forces the node debugger to use the 'legacy' protocol based implementation. This is supported by Node.js versions < v8.0). + +In the future `auto` will be the default, however since the transition to the new node debugging experience hasn't been finished yet (and we were not brave enough to enable it by default), we continue to use `legacy` for the time being. + +But we would like to encourage you to use `'protocol': 'auto'` in your launch configurations and provide feedback if you experience problems. + +## Task support + +### Key bindings per task + +You can now bind a keyboard shortcut to any task you want. + +Simply add a key binding like this: + +```json +{ + "key": "ctrl+h", + "command": "workbench.action.tasks.runTask", + "args": "tsc" +} +``` + +This binds `ctrl+h` to the task named `tsc`. + +### More work on Terminal Runner + +As announced in the previous release, we are working on running tasks in the Integrated Terminal instead of the Output panel. In this release, we added support to compose tasks out of simpler tasks. If, for example, you have a workspace with a client and server folder and both contain a build script, you can now have one task that starts both build scripts in separate terminals. + +The `tasks.json` file looks like this: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "taskName": "Client Build", + "command": "gulp", + "args": ["build"], + "isShellCommand": true, + "options": { + "cwd": "${workspaceRoot}/client" + } + }, + { + "taskName": "Server Build", + "command": "gulp", + "args": ["build"], + "isShellCommand": true, + "options": { + "cwd": "${workspaceRoot}/server" + } + }, + { + "taskName": "Build", + "dependsOn": ["Client Build", "Server Build"] + } + ] +} +``` + +Please note the following things: + +- This support is preliminary and subject to change. +- The terminal task runner can now also be enabled by using the `"version": "2.0.0"` property. + +### Facilitating automation with `${lineNumber}` + +As requested by the [community](https://github.com/Microsoft/vscode/issues/12714), we added a new variable `${lineNumber}` for `tasks.json` and `launch.json`. It resolves to the selected line in the currently opened file. This new variable facilitates automation (e.g. running tests) under cursor selection. + +## Extension Authoring + +### Contributable SCM providers + +We made further progress in February on creating a pluggable Source Control feature set for VS Code. Namely, all Git features were ported over to a [Git extension](https://github.com/Microsoft/vscode/issues/18615). + +All VS Code Insiders will get this new interface and we'll use the March milestone to tune and tweak the experience. You can try this out via the `SCM: Enable Preview SCM` command, which will replace the legacy Git functionality with the experimental one (run `SCM: Disable Preview SCM` to undo). + +### Modal messages + +The `window.showInformationMessage` and similar API calls have been [updated to allow the use of modal message dialogs](https://github.com/Microsoft/vscode/pull/19717). + +Here's an example using the `modal` parameter: + +```typescript +window.showInformationMessage('Do you want to continue?', { modal: true }, 'Yes', 'No'); +``` + +### Context specific visibility of Command Palette menu items + +When registering commands in `package.json`, they will automatically be shown in the **Command Palette** (`kb(workbench.action.showCommands)`). To allow more control over command visibility, we have added the `commandPalette` menu item. It allows you to define a `when` condition to control if a command should be visible in the **Command Palette** or not. + +The snippet below makes the 'Hello World' command only visible in the **Command Palette** when something is selected in the editor: + +```json +"commands": [{ + "command": "extension.sayHello", + "title": "Hello World" +}], +"menus": { + "commandPalette": [{ + "command": "extension.sayHello", + "when": "editorHasSelection" + }] +} +``` + +### Language specific editor settings + +In this release, we added support for following language specific editor settings: + +``` +editor.tabSize +editor.insertSpaces +editor.detectIndentation +editor.trimAutoWhitespace +``` + +**Default language specific editor settings:** Extension authors can now contribute default language specific editor settings using the newly introduced extension point `configurationDefaults` in `package.json`. + +Following example contributes default editor settings for the `markdown` language. + +```json +contributes": { + "configurationDefaults": { + "[markdown]": { + "editor.wordWrap": "on", + "editor.quickSuggestions": false + } + } +} +``` + +### Debug Adapter Protocol + +A new optional attribute `clientID` has been added to the `InitializeRequestArguments`. With this addition, a debug adapter can identify the client (frontend). We maintain a list of client IDs [here](https://github.com/Microsoft/vscode-debugadapter-node/wiki/Client-IDs). + +For obtaining more information about thrown exceptions, we've introduced a new `ExceptionInfoRequest` and a corresponding type `ExceptionDetails`. + + +## Miscellaneous + +### Official signed repositories for Linux + +For Debian-based distributions, we now ship both Stable and Insiders in a signed `apt` repository that is automatically installed when you install the .deb package. This enables automatic updates using the platform's update mechanism. + +![apt repository](images/1_10/apt-repo.jpg) + +For Red Hat-based distributions, we ship Stable in a signed `yum` repository. You can install the repository by following [these instructions](https://code.visualstudio.com/docs/setup/linux#_installation). + +### Monitoring startup performance + +Startup performance is important and we continuously try to improve it. Sometimes startup performance gets slower, mostly because of changes with unintended effects or because of changes in our dependencies. To ensure we see this early and to fix performance regressions, we have started to monitor the startup performance of a dedicated machine. We took a slightly outdated and dusty laptop and set it up as a build machine. Its 'build result' involves starting VS Code a couple of times and sending the startup timings to our telemetry stores. We also created a dashboard with visualizations of that data (PowerBI) and a slack bot (Azure Functions) that tells us once a day what the numbers are. + +![perf bot](images/1_10/performanto.png) + +## Notable Changes + +* [1426](https://github.com/Microsoft/vscode/issues/1426): macOS: file events are not reported when using workspace path with different casing +* [12000](https://github.com/Microsoft/vscode/issues/12000): Terminals created in the background by the API will not display/retain any output until the terminal panel is initialized +* [15364](https://github.com/Microsoft/vscode/issues/15364): Make tabs smaller when workbench.editor.showTabCloseButton: false +* [16820](https://github.com/Microsoft/vscode/issues/16820): Hot Exit: Opens the same file twice in two separate windows +* [19625](https://github.com/Microsoft/vscode/issues/19625): API doesn't update settings if there are trailing commas in settings.json. +* [19526](https://github.com/Microsoft/vscode/issues/19526): Filter installed extensions. +* [10610](https://github.com/Microsoft/vscode/issues/10610): When I hit a breakpoint VS Code opens a new readonly version of the file, breakpoints not shown in gutter. +* [19840](https://github.com/Microsoft/vscode/issues/19840): IntelliSense freezes at random instances +* [19993](https://github.com/Microsoft/vscode/issues/19993): Search perf regression in 1.9 + +These are the [closed bugs](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+label%3Abug+milestone%3A%22February+2017%22+is%3Aclosed) and these are the [closed feature requests](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+milestone%3A%22February+2017%22+is%3Aclosed+label%3Afeature-request) for the 1.10 update. + +## Known Issues + +* [Duplicate errors and warnings](https://github.com/Microsoft/vscode/issues/19627) - This issue may surface more often if the [Preview SCM](#contributable-scm-providers) feature is enabled. + +## Contributions to Extensions + +Our team maintains or contributes to a number of VS Code extensions. Most notably: + +* [Go](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go) +* [TSLint](https://marketplace.visualstudio.com/items?itemName=eg2.tslint) +* [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) +* [Docker](https://marketplace.visualstudio.com/items?itemName=PeterJausovec.vscode-docker) +* [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) +* [Mono Debug](https://marketplace.visualstudio.com/items?itemName=ms-vscode.mono-debug) +* [VSCodeVim](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) + +We also continued the work on our [PHP parser](https://github.com/Microsoft/tolerant-php-parser). We designed it to help extension authors provide better tooling support for PHP. To verify our design and to help the PHP community with concrete first steps, we started to adopt the parser in the [PHP language server](https://github.com/felixfbecker/php-language-server). + +## Thank You + +Last but certainly not least, a big *__Thank You!__* to the following folks that helped to make VS Code even better: + +Contributions to `vscode`: + +* [Chirag Bhatia (@chirag64)](https://github.com/chirag64) + * Fixes #17701 - Integrated Terminal Context Menu is triggered via contextmenu event instead of mousedown [PR #18980](https://github.com/Microsoft/vscode/pull/18980) + * Fixes #18999 - Added .npmignore as a known file type [PR #19387](https://github.com/Microsoft/vscode/pull/19387) + * Fixes #16424 - Added option to toggle matching brackets highlighter [PR #19978](https://github.com/Microsoft/vscode/pull/19978) +* [Collin Grimm (@collinsnji)](https://github.com/collinsnji): Fix #20897 [PR #20899](https://github.com/Microsoft/vscode/pull/20899) +* [Dan Silver (@dan-silver)](https://github.com/dan-silver): Callback parameter for TestEditorService() is optional [PR #20967](https://github.com/Microsoft/vscode/pull/20967) +* [Dustin Campbell (@DustinCampbell)](https://github.com/DustinCampbell): Update to latest C# TextMate grammar [PR #20831](https://github.com/Microsoft/vscode/pull/20831) +* [Joshua Wester (@elemeht)](https://github.com/elemeht): Jenkinsfile are groovy too [PR #16339](https://github.com/Microsoft/vscode/pull/16339) +* [Fred Bricon (@fbricon)](https://github.com/fbricon): Auto-close javadoc [PR #19076](https://github.com/Microsoft/vscode/pull/19076) +* [Gama11 (@Gama11)](https://github.com/Gama11): Some typo fixes [PR #19928](https://github.com/Microsoft/vscode/pull/19928) +* [Anton Vildyaev (@hun1ahpu)](https://github.com/hun1ahpu) + * Fix for issue 12040 [PR #18279](https://github.com/Microsoft/vscode/pull/18279) +* [Ong Heng Le (@initialshl)](https://github.com/initialshl) + * Fix explorer selection state when drag ends [PR #19667](https://github.com/Microsoft/vscode/pull/19667) + * Display one decimal place for extensions downloads in Millions [PR #18702](https://github.com/Microsoft/vscode/pull/18702) +* [Kai Wood (@kaiwood)](https://github.com/kaiwood) + * Include newline when expanding line selection [PR #15564](https://github.com/Microsoft/vscode/pull/15564) + * Enable "Find in selection" within single lines [PR #15566](https://github.com/Microsoft/vscode/pull/15566) +* [katainaka (@katainaka0503)](https://github.com/katainaka0503): Fix colorization of nested list. [PR #19596](https://github.com/Microsoft/vscode/pull/19596) +* [Krzysztof Cieślak (@Krzysztof-Cieslak)](https://github.com/Krzysztof-Cieslak): Fix #15343 - Add `git commit --amend` [PR #17755](https://github.com/Microsoft/vscode/pull/17755) +* [Matheus Cruz Rocha (@matheusrocha89)](https://github.com/matheusrocha89): Terminal encoding problem related to issue #14586 [PR #20932](https://github.com/Microsoft/vscode/pull/20932) +* [Marek Lewandowski (@mlewand)](https://github.com/mlewand): Hotkey for Windows shell context menu [PR #17710](https://github.com/Microsoft/vscode/pull/17710) +* [Marcel Miranda Ackerman (@reaktivo)](https://github.com/reaktivo): Resizes the tab size when dirty file state changes, fixes #15364 [PR #19976](https://github.com/Microsoft/vscode/pull/19976) +* [Ryan Fitzgerald (@rf-)](https://github.com/rf-): Remove dependency on window.event in ListView [PR #20966](https://github.com/Microsoft/vscode/pull/20966) +* [Kazuyuki Sato (@satokaz)](https://github.com/satokaz): markdown-it-named-header custom slugify for non-latin characters [PR #20628](https://github.com/Microsoft/vscode/pull/20628) +* [Alex (@soncodi)](https://github.com/soncodi): Add syntax highlighting for JS/TS template string interpolation (Monokai built-in theme) [PR #17841](https://github.com/Microsoft/vscode/pull/17841) +* [Hugo Duthil (@Swiiip)](https://github.com/Swiiip): Add new cursor styles [PR #14237](https://github.com/Microsoft/vscode/pull/14237) +* [Tim Jones (@tgjones)](https://github.com/tgjones): HLSL syntax highlighting, use HLSL grammar to highlight Cg blocks in ShaderLab files [PR #20129](https://github.com/Microsoft/vscode/pull/20129) +* [Treri Liu (@Treri)](https://github.com/Treri): git clone nvm with --depth 1, to make clone faster [PR #19967](https://github.com/Microsoft/vscode/pull/19967) +* [@typicode](https://github.com/typicode): Update ghooks (deprecated) devDependency [PR #19434](https://github.com/Microsoft/vscode/pull/19434) + +Contributions to `vscode-eslint`: + +* [darkred (@darkred)](https://github.com/darkred): Move the 'Release Notes' from inside 'eslint/README.md' to a separate 'eslint/CHANGELOG.md' [PR #205](https://github.com/Microsoft/vscode-eslint/pull/205) + +Contributions to `language-server-protocol`: + +* [Anton Kosyakov (@akosyakov)](https://github.com/akosyakov): Remove notion of the next tag of the node implementation [PR #171](https://github.com/Microsoft/language-server-protocol/pull/171) +* [bolinfest (@bolinfest)](https://github.com/bolinfest): Contributions to `vscode-languageserver-node`: Introduce DocumentUri concept [PR #170](https://github.com/Microsoft/language-server-protocol/pull/170) +* [Olivier Thomann (@othomann)](https://github.com/othomann): Fix typos [PR #159](https://github.com/Microsoft/language-server-protocol/pull/159) + +Contributions to `vscode-languageserver-node`: + +* [Tobias Bieniek (@Turbo87)](https://github.com/Turbo87): Cleanup "installServerIntoExtension" script [PR #150](https://github.com/Microsoft/vscode-languageserver-node/pull/150) +* [David Greisen (@dgreisen)](https://github.com/dgreisen): MessageBuffer.append: length of string in bytes [PR #163](https://github.com/Microsoft/vscode-languageserver-node/pull/163) + +Contributions to `vscode-languageserver-node-example`: + +* [Leo (@clinyong)](https://github.com/clinyong): fix typo [PR #30](https://github.com/Microsoft/vscode-languageserver-node-example/pull/30) + +Contributions to `vscode-html-languageservice`: + +* [Cody Hoover (@hoovercj)](https://github.com/hoovercj): Add findDocumentSymbols [PR #7](https://github.com/Microsoft/vscode-html-languageservice/pull/7) + + + + diff --git a/release-notes/v1_11.md b/release-notes/v1_11.md new file mode 100644 index 0000000000000000000000000000000000000000..d55a6db380f45dee797ede315a96445f37104eba --- /dev/null +++ b/release-notes/v1_11.md @@ -0,0 +1,532 @@ +--- +Order: 20 +TOCTitle: March 2017 +PageTitle: Visual Studio Code March 2017 +MetaDescription: See what is new in the Visual Studio Code March 2017 Release (1.11) +MetaSocialImage: 1_11/release-highlights.png +--- +# March 2017 (version 1.11) + +**Update 1.11.2**: Adds the 1.11 translations and addresses these [issues](https://github.com/Microsoft/vscode/milestone/41?closed=1). + +**Update 1.11.1**: Fixes these [issues](https://github.com/Microsoft/vscode/milestone/40?closed=1). + +Downloads: [Windows](https://vscode-update.azurewebsites.net/1.11.2/win32/stable) | [Mac](https://vscode-update.azurewebsites.net/1.11.2/darwin/stable) | Linux 64-bit: [.tar.gz](https://vscode-update.azurewebsites.net/1.11.2/linux-x64/stable) [.deb](https://vscode-update.azurewebsites.net/1.11.2/linux-deb-x64/stable) [.rpm](https://vscode-update.azurewebsites.net/1.11.2/linux-rpm-x64/stable) | Linux 32-bit: [.tar.gz](https://vscode-update.azurewebsites.net/1.11.2/linux-ia32/stable) [.deb](https://vscode-update.azurewebsites.net/1.11.2/linux-deb-ia32/stable) [.rpm](https://vscode-update.azurewebsites.net/1.11.2/linux-rpm-ia32/stable) + +--- + +### Troubleshooting + +Some users are reporting issues with the new [Git integration](#git-extension-enabled) and the [keyboard layout support](#improved-keyboard-layout-support). + +If you like to go back to the previous behavior, you can apply the following workarounds: + +* Git integration - Run the **SCM: Disable Preview SCM** command. +* Keyboard layout - Use the setting `"keyboard.dispatch": "keyCode"`. + +## March Release Summary + +Welcome to the March 2017 release of Visual Studio Code. There are a number of significant updates in this version that we hope you will like, some of the key highlights include: + +* **[Preview: Workbench theming](#preview-workbench-theming)** - We're working to make the entire VS Code workbench colors customizable. +* **[Keyboard shortcuts editor](#keyboard-shortcuts-editor)** - New keyboard shortcut editor to easily rebind commands to your preferred shortcuts. +* **[Faster search](#text-search-improvements)** - Faster text search as well as respecting `.gitignore` files. +* **[Panel maximize and restore](#maximize-and-restore-the-panel-size)** - Quickly open panels (Output, Terminal, Debug Console) to full size. +* **[Copy with drag and drop](#drag-and-drop-improvements)** - Choose whether to copy or cut when you drag and drop in the editor. +* **[Terminal link validation](#integrated-terminal)** - Integrated Terminal link validation and new customization settings. +* **[Implementer CodeLens for TypeScript](#implementation-codelens-for-typescript)** - See who implements an interface or abstract class in a CodeLens window. +* **[New Debug menu](#debug-menu)** - Run Debug commands directly from the main menu. +* **[Async call stacks](#async-call-stacks)** - Async JavaScript call stacks now displayed in the debugger. +* **[Source Control API released](#source-control)** - The Source Control API is now public, opening up VS Code to new SCM providers. + +The release notes are arranged in the following sections related to VS Code focus areas. Here are some further updates: + +* **[Editor](#editor)** - New Git SCM provider enabled by default, better file encoding detection, set the default language mode. +* **[Workbench](#workbench)** - Quickly navigate between and resize views, reveal editor if already open. +* **[Languages](#languages)** - TypeScript 2.2.2, simplified TypeScript server log collection, Objective-C++ support. +* **[Debugging](#debugging)** - Column breakpoints improvements, additional exception information. +* **[Node.js Debugging](#node-debugging)** - Call stacks show async frames, access loaded scripts. +* **[Tasks](#tasks)** - Extensions can now provide custom tasks and problem matchers. +* **[Extension Authoring](#extension-authoring)** - Debug extension improvements, increased extension size limit. + +>**Tip:** Want to see new features as soon as possible? You can download the nightly Insiders [build](https://code.visualstudio.com/insiders) and try the latest updates as soon as they are available. + +## Workbench + +### Preview: Workbench theming + +The first results of the effort on workbench theming are now visible. The built-in themes **Abyss**, **Quiet Light**, and **Solarized Dark** take advantage of new color theming capabilities. + + ![Abyss theme with more colors](images/1_11/abyss-theme.png) + +There are still several gaps and we have not finalized the new theme file format. For that reason, there's no documentation and we ask theme authors to not use the new theme format yet. + +However, if you want to play around with new colors, use the setting `workbench.experimental.colorCustomizations` to customize the currently selected theme. + + ![color customization](images/1_11/color-settings.gif) + +### Keyboard shortcuts editor + +With this release, VS Code provides a rich and easy keyboard shortcuts editing experience using a new **Keyboard Shortcuts** editor. You can now find a command and change/remove/reset its key binding easily. Most importantly, you can see key bindings according to your keyboard layout, instead of mapping keys in the earlier json-based key bindings editor to your keyboard layout. The dialog to enter key bindings will assign the correct and desired key binding as per your keyboard layout. + +![Keyboard Shortcuts](images/1_11/keyboard-shortcuts.gif) + +**NOTE:** For more advanced customizations like editing `when` clause context of a key binding, you can open the `keybindings.json` file just like before and edit. + +### Improved keyboard layout support + +On Windows and macOS, we now detect when the keyboard layout has been switched while VS Code is running and will update all keyboard shortcuts appropriately. + +On Linux and macOS, we have made significant changes in how keyboard shortcuts are dispatched; we have switched to using the brand new [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code). This new dispatching logic will result in changes in default keyboard shortcuts for non-US standard keyboard layouts. Unfortunately, due to the indeterminate nature of `KeyboardEvent.keyCode` on these platforms, we cannot be sure in each case the exact changed keybindings and present a list. In most cases, we expect the impact to be limited to the following built-in actions: + +* `Toggle Integrated Terminal` +* `Create New Integrated Terminal` +* `Zoom in`, `Zoom out` +* `Indent Line`, `Outdent Line` +* `Fold`, `Unfold` +* `Split Editor` +* `Toggle Line Comment` + +You can read more in [our wiki](https://github.com/Microsoft/vscode/wiki/Keybinding-Issues) or in the [plan item](https://github.com/Microsoft/vscode/issues/17521). + +> Note: If you experience issues with `KeyboardEvent.code` based dispatching on macOS or Linux, you can use the setting `"keyboard.dispatch": "keyCode"` to force VS Code to dispatch on `KeyboardEvent.keyCode`. + +### Text search improvements + +Search is now powered by the excellent tool [ripgrep](https://github.com/BurntSushi/ripgrep), from Andrew Gallant ([@BurntSushi](https://github.com/BurntSushi)), and searching should now be significantly faster. If you encounter an issue and need to revert to the previous search experience, you can set the option `"search.useRipgrep": false`. + +Our ripgrep-based search can now respect `.gitignore` files as well. Enable it with the new **Use Ignore Files** button in the Search view, or by default with `"search.useIgnoreFilesByDefault": true`. + +![gitignore](images/1_11/search-viewlet.png) + +The gear icon next to it is also new, and toggles whether search will ignore the patterns specified in the `files.exclude` and `search.exclude` settings. + +### Maximize and restore the panel size + +We have added a maximize/restore button to the panel title area: + +![Panel](images/1_11/panel.gif) + +### New setting to keep editor open even when file is deleted + +There is a new setting `workbench.editor.closeOnFileDelete` that can be set to `false` to keep editors open even if the file was deleted on disk. Editors will indicate if the file was deleted on disk with their label. + +![Deleted File](images/1_11/file-deleted.png) + +**Note**: Files that get deleted via the Explorer will still cause the editor to close. + +### Join editors of two groups + +A new command (`workbench.action.joinTwoGroups`) was added to join the editors of one group with the one to the left. This allows to quickly reduce the number of opened editor groups without losing any of the editors inside. + +### Navigate between views + +New commands have been added to navigate between the visible views of the application. For example, when focus is inside the first editor group, `workbench.action.navigateLeft` will bring you to the Side Bar. Similar, `workbench.action.navigateDown` would move focus to the panel. + +### Resize a view with keyboard + +New commands are available to resize the currently focused view with the keyboard. Use `workbench.action.increaseViewSize` and `workbench.action.decreaseViewSize` to change the view size in increments. + +### New setting to reveal editor if opened + +A new setting `workbench.editor.revealIfOpen` can be enabled to prevent opening the same file in another group if the file was already opened. One common scenario is the file picker (Quick Open): by default, it will open a file in the current active Editor Group. Changing this setting will prefer to open the file in any of the other groups in case the file is already opened there. + +**Note**: There are still ways that the same editor will open in multiple groups, for example when you click the split editor action. + +## Editor + +### Drag and drop improvements + +You can now copy selected text instead of moving it when you drag and drop. The experience is the same as you have on your platform. On macOS, press and hold the `Option` key while you drag and drop. Press the `kbstyle(Ctrl)` key on Windows and press the `kbstyle(Alt)` key on Linux. + +When you drag and drop with or without copying the text, the style of the mouse pointer will change accordingly. You will see a `+` (plus) image when copying. + + ![dnd](images/1_11/dnd.gif) + +### Git extension enabled + +The [new Git source control extension](https://code.visualstudio.com/updates/v1_10#_contributable-scm-providers) is now enabled by default. This Git integration goes through the same [extension points](#source-control) as third-party SCM providers. We're still working on the Git extension and if you'd like to go back to the previous version, you can run the **SCM: Disable Preview SCM** command to switch back. + +You can quickly tell if the Git extension is enabled by looking at the **Activity Bar** icon. The new SCM provider integration will show a merge icon instead of the Git icon: + +![scm provider icon](images/1_11/scm-provider-icon.png) + +### Turn off occurrences highlight + +There is a new option, `editor.occurrencesHighlight` that can be set to `false` to turn off highlighting of the selected word or word under cursor in cases where these highlights are computed by a rich language service. + +### Auto guess encoding of files + +You can now let VS Code guess the encoding of a file automatically via the new `files.autoGuessEncoding` setting which is disabled by default. Once enabled, we will do an attempt at guessing the encoding from the file and use that information if there is a suitable encoding detected. + +**Note**: there are cases where the encoding is detected wrongly or not at all. To have full control over the encoding in the workspace, use the `files.encoding` setting instead. + +On top of that, if you select the encoding picker on a file to change its encoding, we will now present you the guessed encoding (if any) to the top of that list, making it very easy to pick the right encoding in case the file contents are not showing correctly and we can detect the encoding from the contents: + + ![encoding](images/1_11/encoding.png) + + **Note**: The encoding is guessed, and can be wrong. There is no 100% accurate way to find the encoding from the contents of a file. The only exception is using a BOM (byte order mark) for UTF-8 or UTF-16 files. + +### More Fuzzy Matching + +We have improved the filtering and scoring of suggestions. In addition to prefix and camel-case matching continuous substring matching is supported. + +![dnd](images/1_11/fuzzy-score.png) + +### IntelliSense in comments + +There is no more eager IntelliSense when typing in comments or strings! You can still request completions with `kbstyle(Ctrl+Space)` but quick suggestions, AKA "24x7 IntelliSense", are disabled by default in comments and strings. To tune the suggestions behavior to your needs, we now allow more control over the `editor.quickSuggestions` setting: + +```json +"editor.quickSuggestions": { + "comments": false, // <- no 24x7 IntelliSense in comments + "strings": true, // but in strings and the other parts of source files + "other": true, +} +``` + +### Set the default language for new files + +A new setting `files.defaultLanguage` can be used to set the language mode for new files that are untitled and not saved yet. This setting avoids having to pick the language each time you open a new file if you are often working on the same file type. + +## Integrated Terminal + +### Link improvements + +The terminal links feature that was introduced last month got some more polish this version. The experience is now aligned with the editor, requiring `kbstyle(Ctrl)` or `kbstyle(Cmd)` to be held depending on your platform. + +![Terminal link hints](images/1_11/terminal-link-hint.png) + +Also all links are now validated so only links that actually go somewhere will react to user action. + +### Improved start experience on Windows + +Unlike on macOS and Linux with their `SHELL` environment variable, Windows doesn't really have a reliable alternative. There is `COMSPEC` but unfortunately it always defaults to the 32-bit variant of Command Prompt and it's seldom modified. To work around this, we've introduced a message when the terminal is first launched on Windows that allows users to select from a set of shells detected on the machine. + +![Terminal shell selector](images/1_11/terminal-shell-selector.png) + +### Custom workspace shell settings + +In VS Code v1.9, we disallowed workspace settings from configuring the terminal shell as it could have potentially been exploited maliciously. We are now re-allowing this but requiring an explicit user opt-in for each workspace before the settings will be picked up. + +![Terminal workspace settings warning](images/1_11/terminal-workspace-warn.png) + +### Warn when closing window with active terminal sessions + +The new setting `terminal.integrated.confirmOnExit` has been added that presents a confirmation dialog when the window is closing with active terminal sessions. This is disabled by default. + +### Resizing horizontally no longer discards data + +Thanks to an [upstream PR](https://github.com/sourcelair/xterm.js/pull/616) from [Lucian Buzzo](https://github.com/LucianBuzzo), data is no longer discarded when resizing the terminal prompt horizontally. + +## Tasks + +In this release, we opened up tasks for contributions from extensions. They can contribute problem patterns and problem matchers via the extension's `package.json` file. These contributions work in both the output panel runner and in the new (not yet the default) terminal runner. Below an example to contribute a problem matcher for the gcc compiler in an extension: + +```ts +{ + "contributes": { + "problemMatchers": [ + { + // the name of the problem matcher + "name": "gcc", + // The problem is owned by the cpp language service. + "owner": "cpp", + // The file name for reported problems is relative to the opened folder. + "fileLocation": ["relative", "${workspaceRoot}"], + // The actual pattern to match problems in the output. + "pattern": { + // The regular expression. Example to match: helloWorld.c:5:3: warning: implicit declaration of function ‘prinft’ [-Wimplicit-function-declaration] + "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$", + // The first match group matches the file name which is relative. + "file": 1, + // The second match group matches the line on which the problem occurred. + "line": 2, + // The third match group matches the column at which the problem occurred. + "column": 3, + // The fourth match group matches the problem's severity. Can be ignored. Then all problems are captured as errors. + "severity": 4, + // The fifth match group matches the message. + "message": 5 + } + } + ] + } +} +``` + +This problem matcher can now be used in a tasks.json via a name reference `$gcc`. An example looks like this: + +```ts +{ + "version": "0.1.0", + "command": "gcc", + "args": ["-Wall", "helloWorld.c", "-o", "helloWorld"], + "problemMatcher": "$gcc" +} +``` + +We also now allow extensions to contribute tasks to the `Run Task` Quick Pick list programmatically. This opens VS Code up for use cases where an extension wants to add support for a specific build system and wants to contribute corresponding tasks. An example is the npm extension that can now contribute scripts defined in the `package.json` as tasks to VS Code programmatically. + +Please note the following limitations: + +- Contributed tasks can only be executed in the new terminal runner. To enable the terminal runner, add `"version": "2.0.0"` to your `tasks.json` file. +- The task API is currently in proposed state. + +For an example of how to use the API, please refer to VS Code's [gulp extension](https://github.com/Microsoft/vscode/tree/master/extensions/gulp) or the proposed API [file](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.proposed.d.ts) + +## Languages + +### TypeScript 2.2.2 + +VS Code now ships with TypeScript 2.2.2. This release includes a number of important bug fixes and performance improvements. You can find a complete list of changes [here](https://github.com/Microsoft/TypeScript/milestone/40?closed=1). + +### Implementation CodeLens for TypeScript + +We now include a CodeLens that shows the number of implementers of interfaces and abstract classes in TypeScript code. + +![TypeScript Implementations CodeLens](images/1_11/ts-implementations-lens.png) + +Clicking on the CodeLens will display a list of all implementations. + +![TypeScript Implementations CodeLens](images/1_11/ts-implementations-lens-expanded.png) + +This feature is disabled by default and requires TypeScript 2.2.1+. To enable it, add `"typescript.implementationsCodeLens.enabled": true` to your settings. + +### Simplified TypeScript server log collection + +Added a new `"typescript.tsserver.log"` setting to simplify the collection of logs from the TypeScript server that powers VS Code's TypeScript and JavaScript language support. These logs can be used to debug issues with JS and TS language support, and make it easier for users to provide these logs during issue investigations. + +The new logging experience is supported with TypeScript 2.2.2+. Set `"typescript.tsserver.log": "verbose"` and reload VS Code to enable logging to a file. Use the `"TypeScript: Open TS Server log"` command to open the log file in the editor. + +### Improved support for Objective C++ + +VS Code now includes an `objective-cpp` language mode for working with Objective-C++. Previously, `.mm` files were treated as regular C++. This release also improves syntax coloring of Objective-C++ files. + +## Debugging + +### Debug Menu + +We have added a top level debug menu with the most common debug commands: + +![Debug Menu](images/1_11/debug-menu.png) + +**Note**: There is a new command (**Install Additional Debuggers...**) to bring up the Extension view to search for debugger extensions. + +### Column Breakpoints Improvements + +It is now possible to edit multiple breakpoints on a line directly from the glyph margin context menu. Apart from this, there were issues with multiple breakpoints on a line which are now fixed. + +![Editable Column Breakpoints](images/1_11/column-breakpoints.png) + +### More detailed exception experience + +The editor's "Peek UI" has been enhanced to show additional information for thrown exceptions, For example, VS Code's built-in Node.js debugging now shows the stack trace: + +![Exception Peek UI show Stack Trace](images/1_11/exception-peekui.png) + +Since this feature requires some adoption effort by debugger extensions, do not expect to see additional exception information in other debugger extensions immediately. + +## Node Debugging + +### Transitioning to the "inspector" protocol + +In the February milestone, we folded the two Node.js debuggers ('node' and 'node2') into a single Node.js debugging experience and introduced a new launch configuration attribute `protocol` to control which protocol to use (for details see the [section in the February release notes](https://code.visualstudio.com/updates/v1_10#_node2-transitioning). + +In this milestone, we've changed the default value for `protocol` from `legacy` to `auto`. So if you don't specify the `protocol` explicitly in your launch configuration, VS Code Node.js debugging will now try to detect the protocol used by the targeted runtime automatically. Since we do not want to switch users to the new "inspector" protocol too aggressively, we will use the new protocol only for 8.x versions of Node.js. + +If you experience problems with this automatic protocol switching, you can get back to the old behavior by explicitly setting `protocol` to `legacy`. + +### Async call stacks + +When debugging async JavaScript in Node.js or Chrome, we now show the async frames that led to the current call stack across async calls. This is currently only supported when debugging with the [inspector protocol](https://code.visualstudio.com/updates/v1_10#_node2-transitioning) via `"protocol": "inspector"`. It can be disabled by setting `"showAsyncStacks": false` in the launch config. + +Example: + +In this code snippet, `fetchData` is an async function that returns a Promise. Without async stacks, we can't see the calls that happened before the Promise was resolved: + +![Async Frames in Call Stack](images/1_11/async-stack-before.png) + + +But with the async call stacks, we can see the full call stack that produced the async call: + +![Async Frames in Call Stack](images/1_11/async-stack-after.png) + +### Access Loaded Scripts + +It is now possible to access the loaded scripts of a JavaScript runtime. This is useful if you need to set a breakpoint in a script that is not part of your workspace and therefore cannot be easily located and opened through normal VS Code file browsing. A typical scenario for this is a remote debugging session: you attach to a remote Node.js program and have no code available locally. See issue [#20355](https://github.com/Microsoft/vscode/issues/20355) for other scenarios that drove this enhancement. + +The **Debug: Open Loaded Script** action (`kb(extension.node-debug.pickLoadedScript)`) gives you access to loaded scripts while a debug session is active. In the Quick Pick, you can filter and select the script to open. The script is then loaded into a read-only editor where you can set breakpoints. These breakpoints are remembered across debug sessions but you only have access to the script content while a debug session is running. + +![Opening Loaded Script with Quick Pick](images/1_11/loaded-scripts.gif) + +## Extension Authoring + +### Source Control + +A stable Source Control API was released this month which lets you create source control extensions integrated within VS Code. You can learn all about it in the [Source Control in VS Code](https://code.visualstudio.com/docs/extensionAPI/api-scm) documentation page. + +Some extension developers have already started adopting it: + +- [vscode-perforce](https://github.com/stef-levesque/vscode-perforce) + +### API Improvements + +* The end of line sequence a document uses (`crlf` or `lf`) is now exposed via `TextDocument#eol`. Also, the `TextEdit` allows you to change EOL-sequence of a document. +* We added these new completion item kinds: `Constant`, `Struct`, and `EnumMember` completing the existing `Enum` kind. + +### Debug Extensions + +* **ExceptionInfoRequest now used by VS Code** + +If a debug adapter returns a non-falsy `supportsExceptionInfoRequest` capability, VS Code will now use the `ExceptionInfoRequest` to obtain additional information for the exception. Currently the attributes `exceptionId`, `exception`, `breakMode`, and `details.stackTrace` are displayed in VS Code's exception Peek UI. + +* **Server mode for debug adapters** + +VS Code always supported running debug adapters in server mode. However this was only officially supported for developing debug adapters, not for running them in production. With this release, we are starting to support the "server mode" as an official "run mode" for debug adapters. Please find the details for how to use this feature in the original [feature request](https://github.com/Microsoft/vscode/issues/22080#issuecomment-286068943). + +* **Changed semantics of `StoppedEvent.reason`** + +The semantics of the `reason` attribute of `StoppedEvent` has been changed slightly. Previously, it was specified that the reason attribute is shown in the UI (which has the consequence that the value needs to be translated to different languages). This makes it impossible for VS Code to interpret the `reason` attribute in a robust way. Starting with this release, VS Code uses the new attribute `description` when the "stopped" reason needs to be shown in the UI and uses the `reason` attribute to interpret the reason. If `description` is missing, VS Code falls back to the previous behavior. + +* **New attribute `presentationHint` for `StackFrame` type** + +A new optional attribute `presentationHint` has been added to the `StackFrame` type which can be used to control how the client renders a stack frame in the UI. + +* **Usage example for exception configuration API** + +The VS Code [Mono debugger extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.mono-debug) has been enhanced to use the recently introduced `exceptionOptions` attribute on the `SetExceptionBreakpointsRequest` for configuring exception catchpoints. + +![Configuring Exceptions](images/1_11/config-exceptions.gif) + +The [implementation](https://github.com/Microsoft/vscode-mono-debug/blob/master/src/typescript/extension.ts#L90) can serve as an example for how to use the debug adapter protocol (DAP) from an extension to add specific functionality that is not provided by the generic VS Code debugger UI. + +### Increase Extension Size Limit + +In a collaboration with the Visual Studio Marketplace, we've increased the size limit of extensions in the Marketplace from 20MB to 100MB. You'll need to update to `vsce@1.20.0` to benefit from this. + +## Miscellaneous + +### Startup profiling for everyone + +We have added a new command line option that allows you to profile the startup of VS Code. Run code like this `code --prof-startup` and it will create profiles for the main and renderer process. These profiles are stored in your home directory and we encourage you to share them with us. Often performance out in the wild is vastly different from our machines and getting more insights from you will help us improve VS Code. + +### Coming Soon: Support for community localization + +VS Code currently ships with support for [9 languages](https://code.visualstudio.com/docs/getstarted/locales): French, Italian, German, Spanish, Russian, Traditional and Simplified Chinese, Japanese, and Korean. In the March release, we started moving the current internal localization process to support the open translation platform called [Transifex](https://www.transifex.com/). + +Once this work is done, we will be able to accept translations from the community directly instead of having to [submit a bug](https://github.com/Microsoft/vscode/issues/5405) and wait for us to localize the string(s).  Even more exciting though, this work enables VS Code to be localized by the community into additional languages such as [Portuguese](https://github.com/Microsoft/vscode/issues/15077) and [Polish](https://github.com/Microsoft/vscode/issues/14241). In fact, we're opening up translations into 8 additional languages: Czech, Dutch, Hungarian, Polish, Portuguese (Brazil and Portugal), Swedish, and Turkish. + +If you are passionate about having a high quality VS Code in your native language, please come and help us!  Learn more at the [Visual Studio Code Community Localization Project](https://github.com/Microsoft/Localization/wiki/Visual-Studio-Code-Community-Localization-Project). + +## New Commands + +Key|Command|Command id +---|-------|---------- +`kb(workbench.action.openSettings)`|Open Settings|`workbench.action.openSettings` +`kb(workbench.action.revertAndCloseActiveEditor)`|Revert and Close Active Editor|`workbench.action.revertAndCloseActiveEditor` +`kb(workbench.action.joinTwoGroups)`|Join Editors of Two Groups|`workbench.action.joinTwoGroups` +`kb(workbench.action.navigateUp)`|Move to the View Part Above|`workbench.action.navigateUp` +`kb(workbench.action.navigateDown)`|Move to the View Part Below|`workbench.action.navigateDown` +`kb(workbench.action.navigateLeft)`|Move to the View Part to the Left|`workbench.action.navigateLeft` +`kb(workbench.action.navigateRight)`|Move to the View Part to the Right|`workbench.action.navigateRight` +`kb(workbench.action.increaseViewSize)`|Increase View Size|`workbench.action.increaseViewSize` +`kb(workbench.action.decreaseViewSize)`|Decrease View Size|`workbench.action.decreaseViewSize` + +## Notable Changes + +* [12077](https://github.com/Microsoft/vscode/issues/12077): File does not reload in editor when quickly changed externally after making modifications +* [13001](https://github.com/Microsoft/vscode/issues/13001): Keep scroll position stable when closing a tab +* [13665](https://github.com/Microsoft/vscode/issues/13665): Improve VS Code when working with network drives +* [19841](https://github.com/Microsoft/vscode/issues/19841): Node debug Step Over/Into hangs in 1.9 +* [20074](https://github.com/Microsoft/vscode/issues/20074): VS Code default language extensions override custom language extensions +* [21948](https://github.com/Microsoft/vscode/issues/21948): Auto save no longer works +* [22900](https://github.com/Microsoft/vscode/issues/22900): CPU usage even when idle (due to cursor rendering) +* [22971](https://github.com/Microsoft/vscode/issues/22971): Run the terminal as a login shell by default on macOS +* [22997](https://github.com/Microsoft/vscode/issues/22997): Execute Node.js application in external terminal throws error +* [23494](https://github.com/Microsoft/vscode/issues/23494): Debugger does not work with electron v1.6.x + +These are the [closed bugs](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+label%3Abug+milestone%3A%22March+2017%22+is%3Aclosed) and these are the [closed feature requests](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+milestone%3A%22March+2017%22+is%3Aclosed+label%3Afeature-request) for the 1.11 update. + +## Contributions to Extensions + +Our team maintains or contributes to a number of VS Code extensions. Most notably: + +* [Go](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go) +* [TSLint](https://marketplace.visualstudio.com/items?itemName=eg2.tslint) +* [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) +* [Docker](https://marketplace.visualstudio.com/items?itemName=PeterJausovec.vscode-docker) +* [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) +* [Mono Debug](https://marketplace.visualstudio.com/items?itemName=ms-vscode.mono-debug) +* [VSCodeVim](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) + +## Thank You + +Last but certainly not least, a big *__Thank You!__* to the following folks that helped to make VS Code even better: + +Contributions to `vscode`: + +* [David Wilson (@daviwil)](https://github.com/daviwil): Add new "files.defaultLanguage" configuration setting. [PR #23220](https://github.com/Microsoft/vscode/pull/23220) +* [Mackenzie McClane (@Aarilight)](https://github.com/Aarilight): Add typescript and javascript format.insertSpaceBeforeFunctionParenthesis [PR #21712](https://github.com/Microsoft/vscode/pull/21712) +* [Anand Dyavanapalli (@adyavanapalli)](https://github.com/adyavanapalli): TypeScript should use double quotes for string in import snippet. [PR #22255](https://github.com/Microsoft/vscode/pull/22255) +* [Adrian Perez (@aperezdc)](https://github.com/aperezdc): Make more descriptive appdata summary field [PR #22965](https://github.com/Microsoft/vscode/pull/22965) +* [Christopher Leidigh (@cleidigh)](https://github.com/cleidigh): Feature/part resize: Add key bindings to resize focused view [PR #22861](https://github.com/Microsoft/vscode/pull/22861) +(https://github.com/Microsoft/vscode/pull/10676) +* [@cristianhosu](https://github.com/cristianhosu): Feature #22768 [PR #23049](https://github.com/Microsoft/vscode/pull/23049) +* [Drazen Dotlic (@ddotlic)](https://github.com/ddotlic): Add option to always reuse open editors [PR #21815](https://github.com/Microsoft/vscode/pull/21815) +* [Dustin Campbell (@DustinCampbell)](https://github.com/DustinCampbell): Update to latest C# TextMate grammar [PR #23179](https://github.com/Microsoft/vscode/pull/23179) +* [Felipe Sateler (@fsateler)](https://github.com/fsateler): Add gnupg and apt to depends [PR #20988](https://github.com/Microsoft/vscode/pull/20988) +* [Cody Hoover (@hoovercj)](https://github.com/hoovercj) + * quickopen and quickoutline will now show the field icon for field symbols [PR #21318](https://github.com/Microsoft/vscode/pull/21318) + * Add backwards search to preferences view [PR #22556](https://github.com/Microsoft/vscode/pull/22556) + * Follow up to PR #22021 to respond to feedback [PR #22178](https://github.com/Microsoft/vscode/pull/22178) + * Add ability to open untitled document with initial content [PR #22021](https://github.com/Microsoft/vscode/pull/22021) +* [Anton Vildyaev (@hun1ahpu)](https://github.com/hun1ahpu): Add 'Focus to terminal X' action [PR #20862](https://github.com/Microsoft/vscode/pull/20862) +* [Ong Heng Le (@initialshl)](https://github.com/initialshl): Implement join editors command [PR #22389](https://github.com/Microsoft/vscode/pull/22389) +* [katainaka (@katainaka0503)](https://github.com/katainaka0503) + * Refactor to fix compile error with noImplicitAny [PR #22460](https://github.com/Microsoft/vscode/pull/22460) + * Auto guess encoding [PR #21416](https://github.com/Microsoft/vscode/pull/21416) + * Refactor to use Promise [PR #21582](https://github.com/Microsoft/vscode/pull/21582) +* [Phawin Khongkhasawan (@lifez)](https://github.com/lifez): Provide "terminal.integrated.enableBold" setting connected to #22422 [PR #22465](https://github.com/Microsoft/vscode/pull/22465) +* [Mark Pearce (@markwpearce)](https://github.com/markwpearce): Checks integrated terminal output for more types of relative paths [PR #22602](https://github.com/Microsoft/vscode/pull/22602) +* [Soo Jae Hwang (@misoguy)](https://github.com/misoguy) + * Add Command for navigating around visible editors/viewlets/repl [PR #22005](https://github.com/Microsoft/vscode/pull/22005) + * Add API to force quit with the ability to revert changes silently [PR #21593](https://github.com/Microsoft/vscode/pull/21593) +* [Paul Daniel Faria (@Nashenas88)](https://github.com/Nashenas88): Fix borderRadius for decorations [PR #22186](https://github.com/Microsoft/vscode/pull/22186) +* [Nick Snyder (@nicksnyder)](https://github.com/nicksnyder) + * Remove duplicate calls to URI.toString() [PR #21283](https://github.com/Microsoft/vscode/pull/21283) + * Avoid request id collisions in pendingRPCReplies [PR #21406](https://github.com/Microsoft/vscode/pull/21406) +* [Jonas Luebbers (@nonphoto)](https://github.com/nonphoto): Make overview ruler border less obtrusive [PR #21459](https://github.com/Microsoft/vscode/pull/21459) +* [Richard Min (@richardmin)](https://github.com/richardmin): Support `...` terminating Yaml FrontMatter [PR #23195](https://github.com/Microsoft/vscode/pull/23195) +* [@rpjproost](https://github.com/rpjproost): Fixed keybinding json for backslash [PR #21969](https://github.com/Microsoft/vscode/pull/21969) +* [Naveen Kumar (@timbanaveen)](https://github.com/timbanaveen): Adding check of full folder name instead of suffix [PR #22532](https://github.com/Microsoft/vscode/pull/22532) +* [Peter V (@vp2177)](https://github.com/vp2177): Exclude CVS directories [PR #22024](https://github.com/Microsoft/vscode/pull/22024) +* [@vsobotka](https://github.com/vsobotka): Fixed typo - fourth instead if forth [PR #22967](https://github.com/Microsoft/vscode/pull/22967) +* [Wissam Abirached (@wabirached)](https://github.com/wabirached): Correctly duplicate files with numbers in filename [PR #22907](https://github.com/Microsoft/vscode/pull/22907) +* [Nicolas Ramz (@warpdesign)](https://github.com/warpdesign): Fixed typo [PR #22921](https://github.com/Microsoft/vscode/pull/22921) +* [Wim Spaargaren (@wimspaargaren)](https://github.com/wimspaargaren): proposal to fix issue 21600 [PR #21859](https://github.com/Microsoft/vscode/pull/21859) + +Contributions to `vscode-chrome-debug-core`: + +* [Manoj Patel (@nojek)](https://github.com/nojvek) + * Support source mapping of stack traces in the Debug Console (and exception widget) [PR #190](https://github.com/Microsoft/vscode-chrome-debug-core/pull/190) + * Nicer error messages when a source map fails to parse [PR #188](https://github.com/Microsoft/vscode-chrome-debug-core/pull/188) +* [Daniel Lebu (@dlebu)](https://github.com/dlebu): Allowing upper case drive letters when handling script URLs. [PR #176](https://github.com/Microsoft/vscode-chrome-debug-core/pull/176) + +Contributions to `language-server-protocol`: + +* [Lucian Wischik (@ljw1004)](https://github.com/ljw1004): DidChange might only have new text [PR #168](https://github.com/Microsoft/language-server-protocol/pull/198) + +Contributions to `vscode-languageserver-node`: + +* [Guillaume Martres (@smarter)](https://github.com/smarter): client: Pass all arguments to ExecuteCommandRequest [PR #172](https://github.com/Microsoft/vscode-languageserver-node/pull/172) +* [Hyo Jeong (@asiandrummer)](https://github.com/asiandrummer): export SocketMessage reader/writer [PR #185](https://github.com/Microsoft/vscode-languageserver-node/pull/185) + +Contributions to `vscode-generator-code`: + +* [@rakkarage](https://github.com/rakkarage): Update vsc-extension-quickstart.md [PR #67](https://github.com/Microsoft/vscode-generator-code/pull/67) +* [John Lianoglou (@prometheas)](https://github.com/prometheas): Making 'Folder name' prompt optional [PR #70](https://github.com/Microsoft/vscode-generator-code/pull/70) + + + + diff --git a/release-notes/v1_12.md b/release-notes/v1_12.md new file mode 100644 index 0000000000000000000000000000000000000000..d2a5e455d859684a4a4c113bd1dad2279bdbfac5 --- /dev/null +++ b/release-notes/v1_12.md @@ -0,0 +1,484 @@ +--- +Order: 21 +TOCTitle: April 2017 +PageTitle: Visual Studio Code April 2017 +MetaDescription: See what is new in the Visual Studio Code April 2017 Release (1.12) +MetaSocialImage: 1_12/release-highlights.png +--- +# April 2017 (version 1.12) + +**Update 1.12.2**: Adds the 1.12 translations and addresses a handful of [issues](https://github.com/Microsoft/vscode/milestone/43?closed=1). + +**Update 1.12.1**: Fixes an [issue](https://github.com/Microsoft/vscode/issues/25918) with .NET debugging. + +**[Workaround for macOS flickering](#macos-flickering)** when running on high DPI external monitors. + +**[Workaround for macOS blurry icons](#macos-blurry-icons)** if certain environment variables are set. + +Downloads: [Windows](https://vscode-update.azurewebsites.net/1.12.2/win32/stable) | [Mac](https://vscode-update.azurewebsites.net/1.12.2/darwin/stable) | Linux 64-bit: [.tar.gz](https://vscode-update.azurewebsites.net/1.12.2/linux-x64/stable) [.deb](https://vscode-update.azurewebsites.net/1.12.2/linux-deb-x64/stable) [.rpm](https://vscode-update.azurewebsites.net/1.12.2/linux-rpm-x64/stable) | Linux 32-bit: [.tar.gz](https://vscode-update.azurewebsites.net/1.12.2/linux-ia32/stable) [.deb](https://vscode-update.azurewebsites.net/1.12.2/linux-deb-ia32/stable) [.rpm](https://vscode-update.azurewebsites.net/1.12.2/linux-rpm-ia32/stable) + +--- + +Welcome to the April 2017 release of Visual Studio Code. For this iteration, we shifted from our usual focus on new features to improving our processes and code base. We reviewed and triaged all our open issues, fixed bugs, and reduced engineering debt. We still think you'll find plenty to be excited about in this release. + +During this milestone, we closed 2199 issues across all VS Code repositories. However, while we were busy closing issues, you were busy opening them. 1925 new issues, to be exact, and we decreased our total issue count by 274. By comparison, in March we closed 1719 issues while we gained 2221 issues, and our total issue count grew by 369. Overall, April looks pretty good. + +And in case you are wondering, out of the 3775 issues that we currently track in [github.com/Microsoft/vscode](https://github.com/Microsoft/vscode/issues), 2368 are feature requests. We won't run out of work anytime soon :-). + +Having this out of the way, we promised the release notes would not be empty: + +* **[Workbench theming ready for authors](#workbench-theming)** - Create and share your own custom VS Code themes. +* **[New source control providers available](#source-control)** - SCM extensions for TFVC, Perforce and Mercurial. +* **[Type checking in JavaScript](#type-checking-for-javascript-files)** - Catch JavaScript programming mistakes early with type checking. +* **[Improved China download speed](#china-downloads)** - Users should see faster downloads (as much as 300x). +* **[Keyboard shortcuts editor](#keyboard-shortcuts-editor)** - Improved keyboard shortcut search and conflict detection. + +>If you'd like to read these release notes online, you can go to [Updates](https://code.visualstudio.com/updates) on [code.visualstudio.com](https://code.visualstudio.com). + +The release notes are arranged in the following sections related to VS Code focus areas. Here are some further updates: + +* **[Workbench](#workbench)** - macOS native Tabs and swipe gestures, terminal link line and column support. +* **[Languages](#languages)** - TypeScript 2.3, apply Markdown snippets on selections. +* **[Debugging](#debugging)** - Context menu to edit watch expressions, better column breakpoints. +* **[Extension Authoring](#extension-authoring)** - Progress UI for long running operations, new completion item types. + + +**Insiders:** Want to see new features as soon as possible? You can download the nightly Insiders [build](https://code.visualstudio.com/insiders) and try the latest updates as soon as they are available. + +## Workbench + +### Workbench theming + +The workbench theming work [started in the March release](https://code.visualstudio.com/updates/v1_11#_preview-workbench-theming) has been continued at full steam. Most gaps are now closed and we are happy to declare the currently available state as 'ready to use' for theme authors. + +Theming support for list & trees (in particular the File Explorer and suggestions widget), diff editor, activity bar, notifications, scrollbar, splitview, buttons and more. + +![activity bar theming](images/1_12/theme-activitybar.gif) + +All built-in themes have been updated to take advantage of the new colors. You can find the full list of all colors in the [Theme Color Reference](https://code.visualstudio.com/docs/getstarted/theme-color-reference). + +![kimbie dark](images/1_12/theme-kimbie-dark.png) + +![solarized-light](images/1_12/theme-solarized-light.png) + +![tomorrow blue](images/1_12/theme-tomorrow-blue.png) + +The new user settings `workbench.colorCustomization` replaces the setting `workbench.experimental.colorCustomization` and lets users change colors on top of the active theme. If you have already used the experimental settings, use the [color id mapping table](https://github.com/Microsoft/vscode/wiki/Color-customization-color-id-changes) to map the ids to the new format. + +The Yeoman generator has been updated to create themes using the new color theme format. In addition, a new command **Developer: Generate Color Theme From Current Settings** is available in the **Command Palette** to help you turn your custom colors to a theme that you can share on the Marketplace. + +We're also looking into ways to make theme creation easier in the [vscode-theme-generator](https://github.com/Tyriar/vscode-theme-generator) project on GitHub. The goal of the generator is to allow generation of good looking themes with as little effort as possible, hiding away the complexities of tweaking the individual workbench color keys and TextMate scopes. + +With the `vscode-theme-generator`, you can create a theme that looks like this by defining only 6 colors: + +![Theme generator preview](images/1_12/theme-generator.png) + +### Keyboard Shortcuts editor + +Search in **Keyboard Shortcuts** editor is improved to support all possible terms for modifier keys in corresponding platforms. + +* `meta`, `cmd`, `command`, `windows` +* `ctrl`, `control` +* `alt`, `option` +* `shift` + +You can now also see the conflicts in the order of precedence. + +![Keyboard shortcuts editor](images/1_12/keyboard-shortcuts-editor.gif) + +### Source control + +Since the SCM API was released, there has been good progress in source control extensions around the community. Here are some of the SCM extensions already published in the Marketplace: + +* [Perforce for VS Code](https://marketplace.visualstudio.com/items?itemName=slevesque.perforce) - Perforce integration. +* [Hg](https://marketplace.visualstudio.com/items?itemName=mrcrowl.hg) - for Mercurial repositories. + +We are very excited about the possibilities of this API and expect more extensions to come out in the near future! + +### Git + +There has been a lot of progress improving the [Git extension](https://github.com/Microsoft/vscode/tree/master/extensions/git) inside VS Code. This Git integration goes through the same [extension points](https://code.visualstudio.com/docs/extensionAPI/api-scm) as third-party SCM providers. + +**Note:** Starting in June, the legacy git integration will be completely removed. Until then, you can still revert back to it using the **SCM: Enable Legacy Git** command. + +### macOS: Sierra Tabs + +With the help of the [Electron update](#electron-update), we can bring back basic support for native macOS Sierra tabs for window management. You can enable them via the `window.nativeTabs` setting after a restart. Once enabled, depending on your OS settings, new tabs will open when you open new windows. Make sure to show the tab bar (**View** > **Show Tab Bar**) to access tabs. + +![native tabs](images/1_12/native-tabs.gif) + +**Note**: Native tabs cannot be used with a custom title. When you enable native tabs, the title bar will change to native styling too. + +### macOS: Mouse swipe to navigate + +We added a new setting `workbench.editor.swipeToNavigate` that allows you to navigate between editors using 3-finger-swipe gesture with the trackpad on macOS. Swiping left or right will navigate across recently used editors in any editor group. This is similar to the **Go** > **Back** and **Go** > **Forward** commands we already had but will skip navigation from occurring within documents. + +**Note**: The same commands that swiping triggers can also be executed via key bindings from the new commands `workbench.action.openPreviousRecentlyUsedEditor` and `workbench.action.openNextRecentlyUsedEditor`. + +**Note**: We currently only support 3-finger-swipe gesture. Make sure that your trackpad settings for swiping are configured like the following to make this work: + +* Swipe between pages: Scroll left or right with three fingers. +* Swipe between full-screen apps: Swipe left or right with four fingers. + +### Integrated Terminal link line and column ranges + +Links to files with line and column ranges are now supported. + +![Terminal line column links](images/1_12/terminal-line-col-link.gif) + +## Languages + +### TypeScript 2.3 + +VS Code now ships with [TypeScript 2.3.2](https://devblogs.microsoft.com/typescript/announcing-typescript-2-3/). This update brings some [new language features](https://github.com/Microsoft/TypeScript/wiki/What's-new-in-TypeScript#typescript-23) and fixes a number of important bugs. + +### Type checking for JavaScript files + +TypeScript 2.3 also brings type checking to plain JavaScript files. This is a great way to catch common programming mistakes and these type checks also enable some exciting quick fixes for JavaScript. + +![Using type checking and quick fixes in a JavaScript file](images/1_12/ts-checkjs-example.gif) + +TypeScript can infer types in `.js` files same as in `.ts` files. When types cannot be inferred, they can be specified using JSDoc comments. You can read more about how TypeScript uses JSDocs for JavaScript type checking [here](https://github.com/Microsoft/TypeScript/wiki/Type-Checking-JavaScript-Files). + +Type checking of JavaScript is optional and opt-in. Existing JavaScript validation tools such as ESLint can be used alongside the new built-in type checking functionality. + +You can get started with type checking a few different ways depending on your needs. + +**Per file** + +The easiest way to enable type checking in a JavaScript file is by adding `// @ts-check` to the top of a file. + +```js +// @ts-check +let easy = 'abc' +easy = 123 // Error: Type '123' is not assignable to type 'string' +``` + +Using `// @ts-check` is a good approach if you just want to try type checking in a few files but not yet enable it for an entire codebase. + +**Using a Setting** + +To enable type checking for all JavaScript files without changing any code, just add `"javascript.implicitProjectConfig.checkJs": true` to your workspace or user settings. This enables type checking for any JavaScript file that is not part of a `jsconfig.json` or `tsconfig.json` project. + +You can opt individual files out of type checking with a `// @ts-nocheck` comment at the top of the file: + +```js +// @ts-nocheck +let easy = 'abc' +easy = 123 // No error +``` + +You can also disable individual errors in a JavaScript file using a `// @ts-ignore` comment on the line before the error: + +```js +let easy = 'abc' +// @ts-ignore +easy = 123 // No error +``` + +**Using a JSConfig or TSConfig** + +To enable type checking for JavaScript files that are part of a `jsconfig.json` or `tsconfig.json`, simply add `"checkJs": true` to the project's compiler options: + +`jsconfig.json`: + +```json +{ + "compilerOptions": { + "checkJs": true + }, + "exclude": [ + "node_modules" + ] +} +``` + +`tsconfig.json`: + +```json +{ + "compilerOptions": { + "allowJs": true, + "checkJs": true + }, + "exclude": [ + "node_modules" + ] +} +``` + +This enables type checking for all JavaScript files in the project. You can use `// @ts-nocheck` to disable type checking per file. + +JavaScript type checking requires TypeScript 2.3. If you are unsure what version of TypeScript is currently active in your workspace, simply run the **TypeScript: Select TypeScript Version** command to check. + +### Change TypeScript versions without reloading VS Code + +Changing the active version of TypeScript no longer requires VS Code to be reloaded. + +### Markdown Preview and Zoom + +With the [update of the Electron](#electron-update) shell, we fixed the issue with clipping of Markdown previews and the in-product release notes when using Zoom. + +### Surround snippets for Markdown + +You can now more quickly bold or italicize text in a Markdown document using snippets. Simply select some text and run the `insert snippet` command. The bold, italic, and quote snippets for Markdown have all been updated to operate on selected text. + +You can also setup a key binding to use these snippets: + +```json +{ + "key": "cmd+k 8", + "command": "editor.action.insertSnippet", + "when": "resourceLangId == 'markdown'", + "args": { + "name": "Insert bold text" + } +} +``` + +## Editor + +### Dynamic IntelliSense sorting + +The editor now re-sorts the completions list while you type. That ensures that the completions you need are always on top and easy to select. + +![Dynamic Sort](images/1_12/completions-dynamic-sort.gif) + +## Tasks + +### Grunt task auto-detection + +Grunt auto-detection has been implemented for the new terminal task runner. With the new terminal runner, tasks are now detected for both [Grunt](https://gruntjs.com) and [Gulp](http://gulpjs.com/) if both corresponding files (`Gruntfile.js`, `gulpfile.js`) are present in a workspace. + +In addition, the proposed task API has been polished. If you had already started to use it, you might encounter some minor breaking changes. + +## Debugging + +### Editing Watch expressions + +It is now possible to edit Watch expressions using the context menu. + +![edit watch](images/1_12/edit-watch.png) + +## Node Debugging + +### Just My Code improvements + +Skipping files when stepping has been available for the `inspector` protocol of the Node.js debugger for three releases. With this release, it is now available for the `legacy` protocol as well. To control a file for skipping, use the context menu command **Toggle skipping this file** on a stack frame in the **CALL STACK** view. + +![toggle skip files](images/1_12/toggle-skip-file.png) + +### Column breakpoints improvements + +Setting breakpoints on a particular column is now supported by the [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) extension, and by the `inspector` protocol of the Node.js debugger, when debugging (yet to be released) Node 8. A column breakpoint can be set using `kb(editor.debug.action.toggleInlineBreakpoint)` or via the context menu during a debug session. + +![column BPs](images/1_12/column-breakpoints.gif) + +## Extension Authoring + +### New APIs + +We have added some new APIs: + +* More completion and symbol item kinds: `Event`, `Operator`, and `TypeParameter`. +* You can now open a text document as a preview editor. This means its tab will be reused when opening another document. This can be done like so: `vscode.window.showTextDocument(doc, { preview: true})`. +* We have added functions to show progress for a long running operation. For now, we have defined two locations for progress in the UI: the **Source Control** view and a window-global progress indication in the Status Bar. + +Take a look at the following sample: + +```ts +vscode.window.withProgress({ + location: vscode.ProgressLocation.Window, + title: 'My long running operation' +}, async (progress) => { + // Progress is shown while this function runs. + // It can also return a promise which is then awaited + progress.report({ message: 'Doing this' }); + await step1(); + + progress.report({ message: 'Doing that' }); + await step2(); +}) +``` + +### Node.js update (6.x to 7.x) + +With the update of Electron to 1.6.6, the Node.js version that is used to run all extensions updated from 6.4.0 to 7.4.0. There are some breaking changes coming with this major update of Node.js, though in general the impact should be minor. Please refer to [this overview](https://github.com/nodejs/node/wiki/Breaking-changes-between-v6-and-v7) for a complete list of breaking changes from Node.js 6 to 7. + +One consequence of the Electron update is that promise rejections are now treated as uncaught exceptions by the Node.js runtime even if the reject is caught later. Since this behavior is annoying when debugging an extension, we've introduced a new exception option to control promise rejections independent from regular exceptions: + +![new promise rejection option](images/1_12/promise-reject-option.png) + +### Debugger extensions + +**`evaluateName` attribute will become mandatory for `Add to Watch` and `Copy Value` actions** + +VS Code tries to implement the **Add to Watch** and **Copy Value** actions by using the data from the **VARIABLES** view and a JavaScript-biased heuristic for building expressions that can be used with the evaluate request. + +Since this approach does not work for all languages, we've introduced the `evaluateName` attribute for variables some time ago. If the `evaluateName` attribute is available for a variable VS Code will use it 'as is' for the evaluate request. If `evaluateName` is missing, VS Code falls back to the old approach. + +Since we plan to remove the fallback completely in the May release, debug adapters must support the `evaluateName` attribute if they want to have the **Add to Watch** and **Copy Value** actions available in the future. + +**New argument `terminateDebuggee` for `disconnect` request** + +An optional argument, `terminateDebuggee`, has been added to the `disconnect` request. If a debug adapter has opted into this feature with the `supportTerminateDebuggee` capability, a client can use this to control whether the debuggee should be terminated when the debugger is disconnected. + +## Miscellaneous + +### Electron update + +In this release, we updated from Electron 1.4.x to 1.6.6. This brings a Chrome update from version 53 to 56 and Node.js from 6.4 to 7.4. Among other things, this update enabled us to bring back native macOS Sierra tabs for window management (behind a setting `window.nativeTabs`) as well as better crash reporting for the processes we spawn. This update also avoids some graphic glitches we have seen on macOS (background artifacts) as well as improved scaling of all UI elements when running with scaling enabled on Windows. + +Unfortunately, we are also seeing some regressions with this update and we ask for your patience until we can move forward to a newer Electron version that fix these issues. + +Specifically: + +* [24981](https://github.com/Microsoft/vscode/issues/24981): Backspace can not erase the last character during Chinese/Japanese IME conversion (macOS) +* [24633](https://github.com/Microsoft/vscode/issues/24633): Unconfirmed text of CJK IME collapse to one character in Integrated Terminal +* [24643](https://github.com/Microsoft/vscode/issues/24643): Webview Flickering on Resize +* [24707](https://github.com/Microsoft/vscode/issues/24707): 1.6.2 update (<1.5) Completely breaks Dragon menu/submenu voice control (updated) +* [25700](https://github.com/Microsoft/vscode/issues/25700): Windows: dropdown selector empty after reload of window + +**Note:** If you are an extension author, please review the impact of this Electron update under the [Extension Authoring](#extension-authoring) section. + +### China downloads + +We've improved the install and update experience for Chinese users, who have always reported slow download speeds when fetching releases of VS Code. We now publish and distribute our releases to network servers located within China so you should start getting much faster speeds in that territory. Some of our test scenarios witnessed a speedup of `300x` ⚡️! + +These improvements are available when downloading VS Code directly from our website as well as when receiving automatic updates. + +## New Commands + +Key|Command|Command id +---|-------|---------- +`kb(workbench.action.openPreviousRecentlyUsedEditor)`|Open Previous Recently Used Editor|`workbench.action.openPreviousRecentlyUsedEditor` +`kb(workbench.action.openNextRecentlyUsedEditor)`|Open Next Recently Used Editor|`workbench.action.openNextRecentlyUsedEditor` +`kb(workbench.action.openGlobalKeybindingsFile)`|Open Keyboard Shortcuts File|`workbench.action.openGlobalKeybindingsFile` + +## Notable Changes + +* [5745](https://github.com/Microsoft/vscode/issues/5745): Webview: apply window.zoomLevel too +* [12473](https://github.com/Microsoft/vscode/issues/12473): macOS Sierra: background artifacts +* [24482](https://github.com/Microsoft/vscode/issues/24482): New Uncaught Exception when starting an extension debugging session +* [24979](https://github.com/Microsoft/vscode/issues/24979): Compound debug configurations not shown after first breakpoint is hit +* [13306](https://github.com/Microsoft/vscode/issues/13306): stepping over breakpoint appears to resume execution fully, vs stepping +* [24126](https://github.com/Microsoft/vscode/issues/24126): Quickly blinking cursor in terminal if you open and quit external app +* [24302](https://github.com/Microsoft/vscode/issues/24302): Use ctrl key as the modifier to enable copy when drag and drop on Linux +* [18351](https://github.com/Microsoft/vscode/issues/18351): Support navigation of problems by keyboard similar to search results. + +These are the [closed bugs](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+label%3Abug+milestone%3A%22April+2017%22+is%3Aclosed) and these are the [closed feature requests](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+milestone%3A%22April+2017%22+is%3Aclosed+label%3Afeature-request) for the 1.12 update. + +## Contributions to Extensions + +Our team maintains or contributes to a number of VS Code extensions. Most notably: + +* [Go](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go) +* [TSLint](https://marketplace.visualstudio.com/items?itemName=eg2.tslint) : We contributed to the [tslint language server plugin](https://github.com/angelozerr/tslint-language-service) and there is now a [preview](https://github.com/angelozerr/tslint-language-service#vscode) available to try out for VS Code. +* [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) +* [Docker](https://marketplace.visualstudio.com/items?itemName=PeterJausovec.vscode-docker) +* [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) +* [Mono Debug](https://marketplace.visualstudio.com/items?itemName=ms-vscode.mono-debug) +* [VSCodeVim](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) + +## Thank You + +Last but certainly not least, a big *__Thank You!__* to the following folks that helped to make VS Code even better: + +Contributions to `vscode`: + +* [Gordon Mckeown(@gmckeown)](https://github.com/gmckeown): Improved rendering of Seti icons [#22667](https://github.com/Microsoft/vscode/issues/22667) +* [@admosity](https://github.com/admosity): Fix typo in inspectKeybindings.ts [PR #25262](https://github.com/Microsoft/vscode/pull/25262) +* [Brian Schlenker (@bschlenk)](https://github.com/bschlenk): Add noValuePreselect option to showInputBox [PR #23827](https://github.com/Microsoft/vscode/pull/23827) +* [Burak Can (@burakcan)](https://github.com/burakcan): Suggestion widget: Fix overflowing text problem (fixes #20679) [PR #20857](https://github.com/Microsoft/vscode/pull/20857) +* [Christopher Leidigh (@cleidigh)](https://github.com/cleidigh) + * Scm css fix for keyboard navigation and actions Issue [PR #23967](https://github.com/Microsoft/vscode/pull/23967) + * Monokai UI theme - first pass for #25327 [PR #25599](https://github.com/Microsoft/vscode/pull/25599) +* [Dick van den Brink (@DickvdBrink)](https://github.com/DickvdBrink): Fixed typo in terminal.contribution description [PR #23784](https://github.com/Microsoft/vscode/pull/23784) +* [David Hewson (@dten)](https://github.com/dten): OK capitalisation fix [PR #25005](https://github.com/Microsoft/vscode/pull/25005) +* [Eric Amodio (@eamodio)](https://github.com/eamodio): Adds editor options overloads to showTextDocument & vscode.diff [PR #23641](https://github.com/Microsoft/vscode/pull/23641) +* [Elias Winberg (@elias-winberg)](https://github.com/elias-winberg): Remove class snippet comment [PR #23209](https://github.com/Microsoft/vscode/pull/23209) +* [William Esz (@flagello)](https://github.com/flagello) + * Escape paths in npm.sh to fix #20907 [PR #21010](https://github.com/Microsoft/vscode/pull/21010) + * Escape paths in code.sh [PR #21016](https://github.com/Microsoft/vscode/pull/21016) +* [@gauss1314](https://github.com/gauss1314): Update typescriptMain.ts [PR #24892](https://github.com/Microsoft/vscode/pull/24892) +* [Vakhurin Sergey (@igelbox)](https://github.com/igelbox): Added support for encodings for Git. [PR #24911](https://github.com/Microsoft/vscode/pull/24911) +* [Ilie Halip (@ihalip)](https://github.com/ihalip): Small comment fix [PR #25558](https://github.com/Microsoft/vscode/pull/25558) +* [Yuki Ueda (@Ikuyadeu)](https://github.com/Ikuyadeu): fix Solarized Light theme highlighting #24040 [PR #24292](https://github.com/Microsoft/vscode/pull/24292) +* [Jordan Menard (@jordanmkasla2009)](https://github.com/jordanmkasla2009) + * Open vscode://file/path/to/project/ URLs properly on Windows - fixes #20290 [PR #20469](https://github.com/Microsoft/vscode/pull/20469) + * Implement #12910 [PR #20881](https://github.com/Microsoft/vscode/pull/20881) +* [Jakub Synowiec (@jsynowiec)](https://github.com/jsynowiec): Add an option to enable/disable JSDoc autocomplete [PR #23704](https://github.com/Microsoft/vscode/pull/23704) +* [Dominic Valenciana (@Kiricon)](https://github.com/Kiricon) + * Added missing . to hc-black so that it displays the correct scm actio… [PR #24385](https://github.com/Microsoft/vscode/pull/24385) + * Changed git renamed icon to orange color [PR #24567](https://github.com/Microsoft/vscode/pull/24567) + * Nested code lines now no longer display the hover border left. [PR #24686](https://github.com/Microsoft/vscode/pull/24686) +* [Phawin Khongkhasawan (@lifez)](https://github.com/lifez): Add zenMode.hideActivityBar option [PR #24499](https://github.com/Microsoft/vscode/pull/24499) +* [Magnus Hiie (@magnushiie)](https://github.com/magnushiie): Expose insert..Braces rule in VS Code settings [PR #21649](https://github.com/Microsoft/vscode/pull/21649) +* [Marek Lewandowski (@mlewand)](https://github.com/mlewand): Added support for home/end key in IntelliSense [PR #20156](https://github.com/Microsoft/vscode/pull/20156) +* [Peter Juras (@peterjuras)](https://github.com/peterjuras): Remove "JOAO" from Readme title [PR #24491](https://github.com/Microsoft/vscode/pull/24491) +* [@QwertyZW](https://github.com/QwertyZW): Let the widgetactions debug UI reflect the state of a focused thread [PR #23878](https://github.com/Microsoft/vscode/pull/23878) +* [Rishii7 (@rishii7)](https://github.com/rishii7) + * Fix #24240 [PR #24371](https://github.com/Microsoft/vscode/pull/24371) + * Fix #24817 - Prevent overflow of the message in define keybinding widget. [PR #24925](https://github.com/Microsoft/vscode/pull/24925) +* [Rômulo Guimarães (@romulo1984)](https://github.com/romulo1984): Update Exec param at code.desktop [PR #24523](https://github.com/Microsoft/vscode/pull/24523) +* [Seivan Heidari (@seivan)](https://github.com/seivan): Fixes #4803: Adding support for swipe gestures on macOS. [PR #23663](https://github.com/Microsoft/vscode/pull/23663) +* [Tereza Tomcova (@the-ress)](https://github.com/the-ress): Fixes #13905: Set relaunch command for window [PR #15407](https://github.com/Microsoft/vscode/pull/15407) +* [Thomas Rayner (@ThmsRynr)](https://github.com/ThmsRynr): Fix #24971. PowerShell Extension .bat & .exe Syntax Highlighting Error [PR #24973](https://github.com/Microsoft/vscode/pull/24973) +* [Naveen Kumar (@timbanaveen)](https://github.com/timbanaveen) + * Adding 'never show again' in Git Extension [PR #24654](https://github.com/Microsoft/vscode/pull/24654) + * Adding line and column support for terminal [PR #24832](https://github.com/Microsoft/vscode/pull/24832) + +Contributions to `language-server-protocol`: + +* [Damien Guard (@damieng)](https://github.com/damieng): Correct log message heading in protocol v1 [PR 186](https://github.com/Microsoft/language-server-protocol/pull/186) +* [Lucian Wischik (@ljw1004)](https://github.com/ljw1004): Change "utf8" to "utf-8" with a hyphen [PR 199](https://github.com/Microsoft/language-server-protocol/pull/199) +* [cxxxr (@cxxxr)](https://github.com/cxxxr): small corrections [PR 205](https://github.com/Microsoft/language-server-protocol/pull/205) +* [Vlad Dumitrescu (@vladdu)](https://github.com/vladdu): small corrections [PR 207](https://github.com/Microsoft/language-server-protocol/pull/207) + +Contributions to `vscode-languageserver-node`: + +* [Cam (@trixnz)](https://github.com/trixnz): Add return value to getEnvironment(). [PR #189](https://github.com/Microsoft/vscode-languageserver-node/pull/189) +* [Guillaume Martres (@smarter)](https://github.com/smarter): Fix a single typo [PR #196](https://github.com/Microsoft/vscode-languageserver-node/pull/196) +* [Hyo Jeong (@asiandrummer)](https://github.com/asiandrummer): fix typo [PR #200](https://github.com/Microsoft/vscode-languageserver-node/pull/200) + +Contributions to `vscode-css-languageservice` + +* [Dominic Valenciana (@Kiricon)](https://github.com/Kiricon): Added @error support for sass [PR #24](https://github.com/Microsoft/vscode-css-languageservice/pull/24) +* [Ryan O'Connor (@rocifier)](https://github.com/rocifier): added unit tests for real selector formatter and fixed indentation [PR #26](https://github.com/Microsoft/vscode-css-languageservice/pull/26) + +## Thank you to our localization contributors + +We opened [community localization](https://code.visualstudio.com/updates/v1_11#_coming-soon-support-for-community-localization) this release and there was a lot of excitement from international users. We now have more than 100 members in the Transifex [VS Code project](https://aka.ms/vscodeloc) team. We appreciate your contributions, either by providing new translations, voting on translations, or suggesting process improvements. + +Here is a snapshot of top contributors for this release. For details about the project including the contributor name list, visit the project site at [https://aka.ms/vscodeloc.](https://aka.ms/vscodeloc) + +* **French:** Vincent Biret. +* **Italian:** Piero Azi, Alessandro Burato, Giuliano Latini, Gianluca Bertelli. +* **German:** Sascha Corti, Jens Suessmeyer, Christian Gräfe, Markus Weber. +* **Spanish:** German Sak, Santiago Porras Rodríguez, José M. Aguilar, Alberto Poblacion. +* **Russian:** Aleksey Nemiro, Kirill Moskvichev, Anton Afonin, Артем Мельниченко, Serge Rodionov, Andrei Pryymak. +* **Japanese:** Yuichi Nukiyama, EbXpJ6bp. +* **Chinese (Simplified):** Joel Yang, Ying Feng, YF. +* **Chinese (Traditional):** Alan Tsai. + +Although the languages below are not yet in VS Code, work is going on there as well. In the May iteration, we will review whether these languages meet the criteria for language integration into VS Code. + +* **Portuguese (Brazil):** Bruno Sonnino, Felipe Caputo, Rodrigo Crespi, Roberto Fonseca, Marcelo Fernandes, Roberto Nunes, Rodrigo Romano, Luan Moreno Medeiros Maciel, Ilton Sequeira, Douglas Eccker. +* **Dutch:** Jeroen Hermans, Gerjan. +* **Polish:** KarbonKitty, Lukasz Korowicki, Paweł Sołtysiak, Jakub Drozdek. +* **Swedish:** Joakim Olsson. +* **Turkish:** Adem Coşkuner, Serkan Inci, Sertac Ozercan. + +## Workarounds + +### macOS flickering + +Some users are seeing VS Code flicker when running on high DPI external monitors [#25934](https://github.com/Microsoft/vscode/issues/25934). The workaround is to set: `"editor.disableTranslate3d": true` in user settings (this produces a warning, but that is fine as VS Code still accepts the setting). + +### macOS blurry icons + +This issue appears if certain environment variables are set when VS Code launches [#24820](https://github.com/Microsoft/vscode/issues/24820). The workaround is to either launch VS Code from the macOS Dock or clear the `LC_ALL` environment variable (`export LC_ALL=`) before launching from the terminal. The [Insiders](https://code.visualstudio.com/insiders) build applies this workaround and clears `LC_ALL`. + + + + diff --git a/release-notes/v1_13.md b/release-notes/v1_13.md new file mode 100644 index 0000000000000000000000000000000000000000..b2914a95c1769373d1e5a99d55ad2ef698f0c4ea --- /dev/null +++ b/release-notes/v1_13.md @@ -0,0 +1,636 @@ +--- +Order: 22 +TOCTitle: May 2017 +PageTitle: Visual Studio Code May 2017 +MetaDescription: See what is new in the Visual Studio Code May 2017 Release (1.13) +MetaSocialImage: 1_13/release-highlights.png +--- +# May 2017 (version 1.13) + +**Update 1.13.1**: The update addresses these [issues](https://github.com/Microsoft/vscode/milestone/45?closed=1). + +Downloads: [Windows](https://vscode-update.azurewebsites.net/1.13.1/win32/stable) | [Mac](https://vscode-update.azurewebsites.net/1.13.1/darwin/stable) | Linux 64-bit: [.tar.gz](https://vscode-update.azurewebsites.net/1.13.1/linux-x64/stable) [.deb](https://vscode-update.azurewebsites.net/1.13.1/linux-deb-x64/stable) [.rpm](https://vscode-update.azurewebsites.net/1.13.1/linux-rpm-x64/stable) | Linux 32-bit: [.tar.gz](https://vscode-update.azurewebsites.net/1.13.1/linux-ia32/stable) [.deb](https://vscode-update.azurewebsites.net/1.13.1/linux-deb-ia32/stable) [.rpm](https://vscode-update.azurewebsites.net/1.13.1/linux-rpm-ia32/stable) + +--- + +Welcome to the May 2017 release of Visual Studio Code. There are a number of significant updates in this version that we hope you will like, some of the key highlights include: + +* **[Changes to settings defaults](#changed-setting-defaults)** - Enabled by default: extensions auto-update, editor drag and drop, and minimap (outline view). +* **[Set multiple cursors with Ctrl/Cmd + Click](#add-multiple-cursors-with-ctrl-cmd-click)** - Add multi-cursors just like Sublime Text and Atom. +* **[Improved Git merge](#merge-conflict-coloring-and-actions)** - Inline merge actions with Accept Changes CodeLens. +* **[Better IntelliSense details](#suggestion-list-and-documentation-side-by-side)** - Easily toggle full suggestion documentation. +* **[Emmet abbreviations display](#emmet-abbreviation-expansion-in-suggestion-list)** - Preview Emmet expansions as you type. +* **[Enhanced snippets](#multi-cursor-snippets)** - Increase your productivity with multi-cursor and nested snippets. +* **[Faster debugger performance](#improved-stepping-performance)** - Stepping through source code is significantly faster. +* **[File links in exception stack traces](#file-link-detection-in-exception-peek-ui)** - Jump directly to source code from exception stack traces. +* **[Docker and MERN debugging recipes](#recipes-for-nonstandard-debugging-scenarios)** - Debug configuration examples for Docker and MERN stack projects. +* **[More workbench theming colors](#new-theming-colors)** - We've added more VS Code customizable colors. +* **[Better NVDA support](#better-nvda-support)** - Accessibility improvements for the NVDA screen reader. + +>If you'd like to read these release notes online, you can go to [Updates](https://code.visualstudio.com/updates) on [code.visualstudio.com](https://code.visualstudio.com). + +The release notes are arranged in the following sections related to VS Code focus areas. Here are some further updates: + +* **[Workbench](#workbench)** - Filenames in symbol search, disable menu bar mnemonics. +* **[Editor](#editor)** - Resizable Find widget, new folding control settings. +* **[Languages](#languages)** - JSX/TSX component highlighting, Markdown headers in symbol search. +* **[Debugging](#debugging)** - Copy All from Debug Console, local/remote paths in launch configurations. +* **[Tasks](#tasks)** - Auto-detect and customize Gulp and Grunt tasks to run in VS Code. +* **[Extension Authoring](#extension-authoring)** - Custom views in the Explorer, reference theme colors. + +**Insiders:** Want to see new features as soon as possible? You can download the nightly [Insiders](https://code.visualstudio.com/insiders) build and try the latest updates as soon as they are available. + +## Setting changes + +### Changed setting defaults + +One thing you may notice right away in the May release is that we've changed the default value of several settings. Features such as minimap (outline view), icon themes, and indent guides have been off by default and we think they are so useful, we want to showcase them. + +![new setting defaults](images/1_13/new-setting-defaults.png) + +Here are the new default settings: + +Setting | New Default | Description +------- | ------- | ---- +`editor.minimap.enabled` | true | Show file minimap (outline view) in the right gutter +`workbench.iconTheme` | "vs-seti" | Use `vs-seti` file icon theme +`editor.renderIndentGuides` | true | Display editor indentation guides +`editor.dragAndDrop` | true | Move editor selections with drag and drop +`extensions.autoUpdate` | true | Automatically update extensions +`window.openFilesInNewWindow` | "off" | Open files in the running VS Code instance + +Of course, you can still configure VS Code to your preference with user or workspace [settings](https://code.visualstudio.com/docs/getstarted/settings) (**File** > **Preferences** > **Settings** or keyboard shortcut `kb(workbench.action.openSettings)`). + +### Add multiple cursors with Ctrl / Cmd + Click + +We have introduced a new setting, `editor.multiCursorModifier`, to change the modifier key for applying multiple cursors to `Cmd+Click` on macOS and `Ctrl+Click` on Windows and Linux. This lets users coming from other editors such as Sublime Text or Atom continue to use the keyboard modifier they are familiar with. + +The setting can be set to: + +* `ctrlCmd` - Maps to `Ctrl` on Windows and `Cmd` on macOS. +* `alt` - The existing default `Alt`. + +There's also a new menu item **Use Ctrl+Click for Multi-Cursor** in the **Selection** menu to quickly toggle this setting. + +The **Go To Definition** and **Open Link** gestures will also respect this setting and adapt such that they do not conflict. For example, when the setting is `ctrlCmd`, multiple cursors can be added with `Ctrl/Cmd+Click`, and opening links or going to definition can be invoked with `Alt+Click`. + +With fixing [Issue #2106](https://github.com/Microsoft/vscode/issues/2106), it is now possible to also remove a cursor by using the same gesture on top of an existing selection. + +## Workbench + +### Filenames in symbol search results + +You can use workspace symbol search (`kb(workbench.action.showAllSymbols)`) to quickly find symbols in your workspace. The list of results now includes the filename of each symbol: + +![symbol search includes filename](images/1_13/typescript-workspace-symbol-names.png) + +### Disable menu bar mnemonics + +A new setting `window.enableMenuBarMnemonics` was added to disable all mnemonics (hot keys) in the menu bar (on Windows and Linux). This frees up some `Alt+` keyboard shortcuts to bind to other commands. + +### Go to Implementation and Go to Type Definition added to the Go menu + +The **Go** menu now includes the **Go to Implementation** and **Go to Type Definition** commands: + +![New Go menu items](images/1_13/go-menu.png) + +### Preserving view state for resource editors + +We are now preserving the view state for resource editors when you switch between them. This comes in handy when debugging internal modules since we now preserve the scroll position and all other view data for internal module editors. However, we always clear the view state when a user closes the editor. + +### High Contrast theme + +We have improved the High Contrast theme to include more token colors and to use selection and Status Bar colors for clearer contrast. + +![High Contrast theme improvements](images/1_13/high-contrast.png) + +### New theming colors + +We received a lot of feedback for our workbench theming support and are happy to see more and more themes adopting the workbench colors! During this milestone, we added almost 50 new colors as well as did some tweaks to existing colors. These colors can be set by themes or directly by the user with the `workbench.colorCustomizations` setting. + +You can review the new colors in the updated [Theme Color Reference](https://code.visualstudio.com/docs/getstarted/theme-color-reference). + +Below are the existing color behavior changes: + +Key|Description +---|------- +`panel.border`|Now overwrites the value of `contrastBorder`, allowing a more specific color if `contrastBorder` is set. +`tab.border`|Now overwrites the value of `contrastBorder`, allowing a more specific color if `contrastBorder` is set. +`editorGroup.border`|Now overwrites the value of `contrastBorder`, allowing a more specific color if `contrastBorder` is set. +`list.*`|All list colors can now be set even in the presence of `contrastBorder` and `contrastActiveBorder`. + +### Multi-root workspaces + +During this milestone, we made some significant steps towards supporting multi-root (multiple project folder) workspaces in VS Code. In case you are wondering why it is taking us a little bit longer to tackle this feature request, please read [Daniel's excellent explanation](https://github.com/Microsoft/vscode/issues/396#issuecomment-301842430). + +We focused on UX and sketched up how we could provide this feature with our current architecture without introducing too many new concepts. After sharing the designs with the engineering team, we ran 2 user studies to validate our assumptions. We encourage you to watch the recordings of these studies if you are interested and provide feedback: + +* group 1: [https://youtu.be/48Y6tB3DN1g](https://youtu.be/48Y6tB3DN1g) +* group 2: [https://youtu.be/kHL6Rt-dLm0](https://youtu.be/kHL6Rt-dLm0) + +With the UX work behind us, we feel that we can finally start implementing this feature request. Thanks for your patience! + +## Editor + +### Merge conflict coloring and actions + +Inline merge conflicts are now colored and come with actions to accept either or both of the changes. Previously available as the popular Better Merge extension, this functionality is now built-in. Thanks to [Phil Price (@pprice)](https://github.com/pprice), the author of Better Merge, for the PR. + +![markdown symbols with header level](images/1_13/merge-conflict.png) + +### Suggestion list and documentation side by side + +When IntelliSense autocomplete/suggestions are triggered, press `kb(toggleSuggestionDetails)` to view the documentation for the suggestion item in focus as before. The documentation will now expand to the side instead of being overlaid on the suggest widget, enabling you to read the documentation and navigate the list at the same time. + +![auto expanded docs in autocomplete](images/1_13/suggest.gif) + +When the documentation fly-out is expanded, it will stay expanded (across VS Code windows, sessions and updates) every time autocomplete/suggestions is triggered, until you explicitly close it either using the close button or by pressing `kb(editor.action.triggerSuggest)` again. + +For keyboard centric users who want to navigate up and down long documentation, press `kb(toggleSuggestionFocus)` to move the focus to the documentation fly-out such that it can now receive keyboard shortcuts for Page Up/Down actions. + +For screen reader users, once the documentation fly-out is expanded, navigating the suggestion list will read out the label and documentation (if any) of the item in focus. + +### Emmet abbreviation expansion in suggestion list + +Until now, the default behavior for expanding an Emmet expansion has been to use the `kbstyle(Tab)` key. There were two issues with this design: + +* Many unexpected Emmet expansions occurred when the user wanted to just add an indent. +* On the other hand, items from the suggestion list got inserted when the user was expecting the Emmet abbreviation to be expanded. + +Both of these issues can be now solved by having the expanded Emmet abbreviations show up in the suggestion list and freeing up the `kbstyle(Tab)` key for what it was meant to do, indenting. + +Set `emmet.useNewEmmet` to `true` to start using this new feature. This feature is best used with the suggestion documentation fly-out expanded where you can preview the expanded abbreviation as you type. Note that `kbstyle(Tab)` key will no longer expand the abbreviation by default. + +![Emmet abbreviation expansion in autocomplete](images/1_13/emmet.gif) + +If you have `editor.quickSuggestions` turned off, you can use one of the methods below to get Emmet expansion: + +* Manually trigger the suggestion by pressing `kb(editor.action.triggerSuggest)` and then choose the expansion from the suggestion list. +* Run the command **Emmet: Expand Abbreviation** explicity from the **Command Palette**. +* Bind your own keyboard [shortcut](https://code.visualstudio.com/docs/getstarted/keybindings) to **Emmet: Expand Abbreviation** (command id `editor.emmet.action.expandAbbreviation`). + +You will see two kinds of suggestions in HTML-like files: + +* The expansion for the abbreviation that has been typed (you can turn this off by setting `emmet.showExpandedAbbreviation` to `false`). +* All possible abbreviations whose prefix is the text that has been typed (you can turn this off by setting `emmet.showAbbreviationSuggestions` to `false`). For example, `a`, `a:link`, `a:mail`, `area` are suggested when you type `a`. This is helpful for discovering Emmet abbreviations. + +In CSS/LESS/SCSS files, you will only see the single abbreviation you have typed. + +To implement this feature, we replaced the single monolithic [Emmet library](https://github.com/emmetio/emmet) with smaller re-usable [Emmet modules](https://www.npmjs.com/%7Eemmetio). In doing so, most of the Emmet commands were re-implemented. If you see any changes in the behavior of any Emmet commands, please create an issue. We hope to complete this work in the next milestone, after which the setting `emmet.useNewEmmet` will be deprecated and the new model will be made default. + +### Multi cursor snippets + +You can now combine snippets and multiple cursors. + +![multi cursor snippets](images/1_13/snippets-multi-cursor.gif) + +In addition, you also now nest snippets, meaning you can add a placeholder of a snippet within another snippet and their placeholders will be merged. + +### Strict snippets + +Snippets can have placeholders and variables. The snippet syntax is defined [here](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_snippet-syntax) where `$1, $2...` are tabstops and `$varName1, $varName2...` are variables. Note that they can only differ by what follows the `$`-sign, numbers are tabstops and words refer to variables. Prior to this milestone, VS Code was using an internal syntax for snippets. Textmate-style snippets were rewritten to the internal syntax and there was an unfortunate bug that caused variables to be turned into tabstops. This is what we have done to ensure a smooth transition: + +* When we encounter snippets that use variables we don't [know](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables), we turn them into placeholders and warn the extension author (not the end user). +* Also, we log a telemetry event so can make issues/PRs against extensions that are using this unfortunate construct. + +In the future, you can expect us to continue to support these types of snippets for a little longer. Snippets fall into two categories; those that the user created and those that come from an extension. We will be strict on extension snippets while keeping support for user created snippets. + +### Find widget + +You can now resize the Find widget horizontally. You can review the full text easily if it's longer than the original width of the Find widget. + +![Resize Find widget](images/1_13/resize-find-widget.gif) + +Also you can now scroll beyond the first line when the Find widget is visible and the Find widget won't cover the matched results. We'll automatically scroll the window a little bit to make sure the matched results are not covered by the Find widget when you are navigating between them. + +![Uncover matched results](images/1_13/uncover-matched-results.gif) + +We introduced two settings to help you customize the Find widget behaviors: + +* You can now set `editor.find.seedSearchStringFromSelection` to `false` if you don't want to seed the search string in Find widget from current editor selection. +* You can set `editor.find.autoFindInSelection` to `true` and then Find in Selection flag is turned on when multiple characters or lines of text are selected in the editor. + +We also added a new command `toggleFindInSelection` (`kb(toggleFindInSelection)`) to toggle Find In Selection so you can keep your hands on the keyboard when switching all Find options. + +### Folding controls + +The visibility of the folding controls next to the line numbers can now be configured by the setting `editor.showFoldingControls`: + +* `mouseover` - The existing behavior where controls for non-collapsed regions are hidden unless the mouse cursor is over the editor gutter. +* `always`- Folding controls are always shown. + +### Letter spacing + +Thanks to [@hoovercj](https://github.com/hoovercj) in [PR #22979](https://github.com/Microsoft/vscode/pull/22979), there is a new editor setting, `editor.letterSpacing`, similar to the CSS letter-spacing property: + +![letter spacing](images/1_13/letter-spacing.gif) + +## Integrated Terminal + +### Dragging files to the terminal to paste path + +You can now drag files and folder from the File Explorer and files from your OS file manager to paste the path name into the terminal. + +### Unicode character width improvements + +Unicode characters in the Integrated Terminal are now sized explicitly which means that applications like [vtop](https://www.npmjs.com/package/vtop) which make extensive use of these characters should now render correctly. + +Before: + +![Better unicode width before](images/1_13/terminal-vtop-before.png) + +After: + +![Better unicode width after](images/1_13/terminal-vtop-after.png) + +## Tasks + +### Run tasks in the Integrated Terminal + +You can now configure tasks so that they are executed inside the Integrated Terminal. By adding a `runner` property to the `tasks.json` file as shown below you enable the Integrated Terminal. + +```ts +{ + "version": "0.1.0", + "runner": "terminal", + ... +} +``` + +If you want to switch back to the old runner, remove the property or set its value to `"process"`. + +### Preview: Tasks version 2.0 + +You can opt into the new tasks version 2.0.0 but please note that this version is currently a preview and still under active development. We make it available in order to get early feedback. + +To enable the tasks preview, set the `version` attribute to `"2.0.0"` : + +```json +{ + "version": "2.0.0" +} +``` + +With version 2.0.0 enabled, the tasks from different task runners like Gulp or Grunt are automatically detected and you can run them with the `Run Task` command. Tasks are currently auto detected from the task runners Gulp, Grunt, Jake, and from the scripts section in `package.json` files. We will provide an API so that you can contribute task detection for other task runners. This API has been further polished during this iteration, but we left in the proposed state for this release (see [vscode.proposed.d.ts](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.proposed.d.ts#L13)). + +The task selection dialog now shows you both tasks that you have configured in the `tasks.json` file and tasks that where automatically detected. For example, in a workspace with a gulp file defining a `build` and a `watch` task and a `tasks.json` file that defines a `Deploy` task, the task selection dialog looks as follows: + +![task selection](images/1_13/task-selection.png) + +When the system detects a task (for example, a build task provided through a gulp file), it usually doesn't know which problem matchers to associate with the task. You can customize a detected task inside the `tasks.json` file. To do so, press the gear icon to the right of a detected task. This will insert a section into the `tasks.json` file where you can customize the detected task. + +The video below illustrates how to customize the gulp `build` task by adding the TypeScript problem matcher (named `$tsc`) to it and by renaming it to `My Main Build`. + +![task customize](images/1_13/task-customize.gif) + +## Debugging + +### Improved stepping performance + +Per a [user recommendation](https://github.com/Microsoft/vscode/issues/25605), we've improved stepping performance by fetching parts of the call stack and the corresponding variables lazily, only if the user has not already requested the next "step" operation. With this change, VS Code will always fetch the top frame of the stack in order to be able to show the correct source for the current location. The rest of the stack will be updated only if the user has not continued stepping for 0.4 seconds. + +This improves stepping performance considerably as you can see in the following screen recordings of the (rather large) [Typescript compiler](https://github.com/Microsoft/TypeScript). + +Old behavior - Always fetch full call stack: + +![step before](images/1_13/step-before.gif) + +New behavior - Fetch rest of the call stack lazily: + +![step after](images/1_13/step-after.gif) + +### File link detection in Exception Peek UI + +When an exception occurs, developers commonly follow through the exception stack trace to understand what caused it. We added a mechanism to detect links in the stack trace returned by the debug adapter. This allows you to jump to your source code straight from the exception UI. Moreover, it also improved existing link detection in a Debug Console, fixing several the user reported issues. + +![File Link Detection in Exception Peek UI](images/1_13/exception-link-detection.png) + +### Recipes for nonstandard debugging scenarios + +Setting up Node.js debugging can be challenging for some non-standard or complex scenarios. With this release, we've started to collect recipes for these scenarios in a new [repository](https://github.com/Microsoft/vscode-recipes). + +The initial recipes cover [Debugging TypeScript in a Docker Container](https://github.com/Microsoft/vscode-recipes/tree/master/Docker-TypeScript) and [Developing the MERN Starter in VS Code](https://github.com/Microsoft/vscode-recipes/tree/master/MERN-Starter). + +### Copy All action in Debug Console + +It is now possible to copy all the content from the Debug Console using the **Copy All** context menu action. More details about what motivated this change can be found [here](https://github.com/Microsoft/vscode/issues/2163). + +![copy all](images/1_13/copy-all.png) + +### New setting `debug.internalConsoleOptions` + +It is now possible to control the behavior of the Debug Console using the setting `debug.internalConsoleOptions`. Previously this setting was only available in `launch.json`, however by [user request](https://github.com/Microsoft/vscode/issues/18398), it is now possible to also specify this in user and workspace settings. The setting in `launch.json` takes precedence if both are provided. + +## Node Debugging + +### Local/remote path mapping now supported for "launch" configurations + +To facilitate remote debugging, VS Code already supports mapping JavaScript paths between a local VS Code project and a (remote) location by means of the `localRoot` and `remoteRoot` attributes. Because remote debugging typically involves "attaching" to a remote target, the `localRoot` and `remoteRoot` attributes were only available for launch configurations of request type `"attach"`. + +Recently we've opened up launch configurations of request type `"launch"` to launch arbitrary programs and scripts (and not just the local Node.js target to debug). With this, it becomes possible to launch a remote Node.js target (for example in a Docker container) and have the VS Code Node.js Debugger attach to it. This feature diminishes the difference between "launching" and "attaching" even further and it makes sense to support `localRoot` and `remoteRoot` attributes for launch configurations of request type `"launch"` as well (in addition to request type `"attach"`). + +You can find an example for this in the [Debugging TypeScript in a Docker Container](https://github.com/Microsoft/vscode-recipes/tree/master/Docker-TypeScript#further-simplifying-the-debugging-setup) recipe. + +## Extensions + +### Enable / Disable commands + +There are two new commands in the **Extensions** view context menu to help quickly manage your extensions: + +* Enable / Disable All Installed Extensions +* Enable / Disable Auto Updating Extensions + +![Extensions actions](images/1_13/extensions-actions.png) + +## Languages + +### Syntax coloring for JSX/TSX components + +In React JSX and TSX files, component classes are now colored differently than normal HTML elements: + +![new jsx coloring](images/1_13/jsx-new-coloring.png) + +### Additional JSDoc tags in hover and suggestions + +JSDoc tags such as `@deprecated` and `@private` are now displayed in hover and suggestions documentation. + +![JSDocs tags sections](images/1_13/jsdocs.png) + +### Open TS Server Log reveals log folder + +The **TypeScript: Open TS Server Log** command now reveals the TypeScript log directory on your operating system instead of trying to open the log file in VS Code. This is useful for collecting the additional Type Declaration (typings) installer log files generated alongside the main `tsserver.log` file. + +### Markdown preview preserves scroll position + +The Markdown preview, along with other webview based views such as the release notes, will now preserve the scroll position when switching between editors. Previously, navigating away from the Markdown Preview and then returning to it caused the scroll position to be reset. + +### Warnings for missing Markdown preview styles + +We now display a warning message if any of the stylesheets from `markdown.styles` used in the preview cannot be found. + +### Markdown symbol search includes heading levels + +You can quickly jump to a heading in a Markdown file using **Go to Symbol in File...** (`kb(workbench.action.gotoSymbol)`). This list now includes the heading level of each symbol, which allows you to quickly filter results by heading level. + +![markdown symbols with header level](images/1_13/markdown-heading-levels.png) + +## Extension Authoring + +### Custom views + +There has been a popular request to customize VS Code to show custom data views, for example a `Node Dependencies` view. With this release, you can now write extensions to VS Code contributing such views. Currently custom views are shown only in Explorer. In future, we will support displaying them in other places too. + +![Custom view](images/1_13/views.png) + +Contributing a view is as simple as follows: + +* Contribute a view using the [views](https://code.visualstudio.com/docs/extensionAPI/extension-points#_contributesviews) extension point. +* Register a data provider for the view using the [TreeDataProvider](https://code.visualstudio.com/docs/extensionAPI/vscode-api#_TreeDataProvider) API. +* Contribute actions to the view using `view/title` and `view/item/context` locations in [menus](https://code.visualstudio.com/docs/extensionAPI/extension-points#_contributesmenus) extension point. + +You can refer to examples in our [extension samples repository](https://github.com/Microsoft/vscode-extension-samples/tree/master/tree-view-sample). + +### Debugger extensions + +**New enum value `subtle` for the `presentationHint` attribute of type `StackFrame`** + +A debug adapter can flag a stack frame with the presentation hint `subtle` in order to receive an alternative "subtle" rendering. + +**Extended type for `TerminatedEvent.body.restart` attribute** + +The type of the `TerminatedEvent.body.restart` attribute has been extended from `boolean` to `any`. This makes it possible to loop arbitrary data from one debug session to the next (restarted) debug session. + +**`evaluateName` attribute mandatory for `Add to Watch` and `Copy Value` actions** + +VS Code previously tried to implement the **Add to Watch** and **Copy Value** actions by using the data from the **VARIABLES** view and a JavaScript-biased heuristic for building expressions that can be used with the evaluate request. + +Since this approach does not work for all languages, we've introduced the `evaluateName` attribute for variables some time ago. It is now mandatory for debug adapters to support the `evaluateName` attribute if they want that **Add to Watch** and **Copy Value** actions work properly. + +### Glob patterns for `workspaceContains` activation event + +Thanks to [@eamodio](https://github.com/eamodio), with [PR #24570](https://github.com/Microsoft/vscode/pull/24570), it is now possible to activate an extension when a folder is opened that contains at least one file that matches a glob pattern. + +For example, an extension with the `package.json`: + +```json +{ + ... + "activationEvents": [ + "workspaceContains:**/.editorconfig" + ] +} +``` + +will be activated when a folder is opened and any of its sub-folders contains a file named `.editorconfig`. + +### Defining a language's word pattern in the language configuration file + +Thanks to [@hoovercj](https://github.com/hoovercj), with [PR #22478](https://github.com/Microsoft/vscode/pull/22478), it is possible to specify a language's word pattern using `wordPattern` in the language configuration file. This used to be possible before only by invoking `vscode.languages.setLanguageConfiguration(...)`. + +### Better control decorations in the editor + +Thanks to [@CoenraadS](https://github.com/CoenraadS), with [PR #25776](https://github.com/Microsoft/vscode/pull/25776), it is now possible to configure the behavior of decorations when typing/editing at their edges. This can be configured with the `DecorationRenderOptions.rangeBehaviour` field. + +### Reference theme colors from extensions + +You can now use theme colors in decorators and for the Status Bar foreground. Using theme colors instead of actual color values is the preferred way as it lets themes and users customize the colors. + +```typescript + var decorationType = vscode.window.createTextEditorDecorationType({ + before: { + contentText: "\u26A0", + color: new vscode.ThemeColor('editorWarning.foreground') + } + }); +``` + +You will find the list of theme colors [here](https://code.visualstudio.com/docs/getstarted/theme-color-reference). + +## Accessibility + +### Better NVDA support + +Sometimes, when using arrow keys, some lines or characters would be repeated by NVDA (see [Issue #26730](https://github.com/Microsoft/vscode/issues/26730)). Thanks to [James Teh](https://github.com/jcsteh), one of the co-founders of [NV Access](https://www.nvaccess.org/), we now understand the root cause (a timeout of 30ms, which we sometimes miss). James has a [PR on NVDA](https://github.com/nvaccess/nvda/pull/7201) where he is changing the default timeout to 100ms and making it configurable. Until a new NVDA version is shipped, thanks to [Derek Riemer](https://github.com/derekriemer), there is an [NVDA plugin](https://files.derekriemer.com/globalEditorTimer-1.0.nvda-addon) that increases the timeout from 30ms to 200ms. We have also done some changes on our side to reduce the likelihood that we miss the 30ms timeout. + +### "Screen Reader Detected" + +We are now leveraging [Electron APIs](https://github.com/electron/electron/blob/master/docs/api/app.md#event-accessibility-support-changed-macos-windows) to react and optimize VS Code when working with a screen reader. Whenever Electron identifies that a screen reader is attached, we will display a message in the Status Bar and: + +* Remove the Line Number and Column indicator from the Status Bar, as we have found updating these indicators causes a myriad of accessibility events that end up confusing screen readers. +* Disable word wrapping, as when pressing arrow down for example, screen readers expect the cursor to move to the next line and not to a column to the right on the same line. +* Mirror the current page of text in the editor synchronously to the `