TypeSpec Visual Studio 扩展安装、tsp-server 路径配置与命令行管理实战【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec本篇文章以 TypeSpec 官方文档中 Visual Studio 扩展一节vs.md为核心系统讲解 TypeSpec VS 扩展的安装方式、typespec.tsp-server.path工作区配置与变量插值规则以及基于tsp vsCLI 的安装/卸载管理。读完本文你将掌握在 Visual Studio 17.x 中接入 TypeSpec 语言服务、把语言服务器指向项目内typespec/compiler的完整方案并能结合本仓库源码理解其底层实现原理。一、扩展概览TypeSpec 的 Visual Studio 语言支持TypeSpec 仓库中对应 Visual Studio 的语言支持包位于 packages/typespec-vs其 package.json 将该扩展标识为 TypeSpec Language Support for Visual Studio。从 packages/typespec-vs/README.md 可以看到该扩展提供的能力包括实时诊断报告Live diagnostic reporting语法高亮Syntax highlighting代码补全Code completion代码折叠Code folding格式化Formatting悬停信息Hover info重命名重构Rename refactoring跳转到定义Go to definition这些能力本质上由 TypeSpec 语言服务器tsp-server提供Visual Studio 扩展只是作为 LSPLanguage Server Protocol 的源码可以看到扩展通过ILanguageClient接口注册名为TypeSpec的语言客户端并监听.tsp、tspconfig.yaml、.cadl、cadl-project.yaml、package.json等文件[Export(typeof(ILanguageClient))] [ContentType(typespec)] public sealed class LanguageClient : ILanguageClient { public string Name TypeSpec; public IEnumerablestring? ConfigurationSections { get; } new[] { typespec }; public IEnumerablestring FilesToWatch { get; } new[] { **/*.tsp, **/tspconfig.yaml, **/package.json, **/*.cadl, **/cadl-project.yaml }; }同时ContentDefinition 将.tsp、.cadl文件扩展名和tspconfig.yaml文件名映射到typespec内容类型从而在 VS 中触发该语言服务。二、安装扩展2.1 通过扩展管理器安装官方推荐官方文档给出的安装方式是通过Visual Studio 扩展管理器从Visual Studio Marketplace安装Marketplace 中该扩展的标识为typespec.typespecvs发布者typespec扩展名typespecvs参见 packages/typespec-vs/publishManifest.json。操作路径为Visual Studio 菜单扩展Extensions→ 管理扩展Manage Extensions→ 联机Online搜索 TypeSpec 后点击下载并安装按提示重启 Visual Studio 即可生效。2.2 通过tsp vs install命令行安装除了扩展管理器TypeSpec 编译器 CLI 也提供了对应命令。在 cli.ts 中注册了tsp vs子命令组tsp vs ├── tsp vs install # Install Visual Studio Extension. └── tsp vs uninstall # Uninstall VS Extension其实现位于 packages/compiler/src/core/cli/actions/vs.tsinstallVSExtensionvs.ts先从 Marketplace 下载 VSIX再调用VSIXInstaller.exe安装。它支持两个“非错误”退出码1001扩展已安装与2005用户取消。uninstallVSExtensionvs.ts调用VSIXInstaller.exe /uninstall:88b9492f-c019-492c-8aeb-f325a7e4cf23卸载其中 GUID 即扩展包注册的包标识见 VSExtension.cs。需要注意的适用前提均为源码可确认的事实仅支持 WindowsgetVSInstallerPath在非win32平台直接返回vs-extension-windows-only诊断vs.ts。该命令会从ProgramFiles(x86)\Microsoft Visual Studio\Installer下查找vswhere.exe与VSIXInstaller.exe。Visual Studio 版本要求通过vswhere检测的受支持版本范围为[17.0,)即 Visual Studio 2022 及更新版本vs.ts。命令已标记为弃用installVSExtension与uninstallVSExtension都调用了reportDeprecatedCommandvs.ts提示优先使用扩展管理器或 Marketplace 安装命令行路径仅作备用。三、配置 tsp-server 路径扩展安装完成后TypeSpec 语言服务器默认如何被定位以及如何强制指定其路径是配置环节的核心。3.1 配置步骤官方文档给出的配置过程分两步在项目根目录创建.vs/VSWorkspaceSettings.json文件以键值对形式写入配置例如{ typespec.tsp-server.path: ${workspaceFolder}/my-nested-project/node_modules/typespec/compiler }该配置项的作用是指定tsp-server的启动入口。从源码实现看读取该配置的逻辑位于 VSExtension.cs 的LoadSettingsAsync当存在 VS 工作区文件夹模式时通过workspace.GetSettingsManager()?.GetAggregatedSettings(SettingsTypes.Generic)读取聚合设置并读取typespec.tsp-server.path属性当打开的是解决方案.sln时扩展会自行解析 .vs/VSWorkspaceSettings.json 文件将其中所有字符串类型的键值对读入配置字典非字符串值会被过滤掉参见 ReadSettingsFromJson。说明typespec.tsp-server.path指向的是typespec/compiler包的根目录例如node_modules/typespec/compiler而不是某个单独的二进制文件。扩展在解析时会在此基础上拼接cmd/tsp-server.js作为实际入口见下文 3.3 节。3.2 变量插值规则TypeSpec 支持在配置值中使用${name}形式的变量插值。官方文档示例中的${workspaceFolder}对应 Visual Studio 工作区的根目录。插值的底层实现位于 VariableResolver.cs核心逻辑如下private const string VARIABLE_REGEXP \$\{(.*?)\}; public static string ResolveVariables(string value, IDictionarystring, string variables) { return Regex.Replace(value, VARIABLE_REGEXP, (match) { var group match.Groups[1]; if (group ! null variables.TryGetValue(group.Value, out var variable)) { return variable; } return match.Value; // 未注册的变量保持原样 }); }从中可以确认两个细节插值语法为\$\{(.*?)\}即${变量名}未注册的变量不会被替换会原样保留在路径字符串中。因此在使用自定义变量前务必确认该变量已在 VS 工作区上下文中注册当前可用的内置变量为workspaceFolder对应工作区根目录在解决方案模式下对应.sln所在目录参见 GetSolutionFolderAsync。插值在路径解析流程中的位置见 VSExtension.cs扩展先构造variables字典仅注册workspaceFolder再调用VariableResolver.ResolveVariables完成替换最后通过Path.GetFullPath归一化为绝对路径。3.3 服务器路径的解析优先级理解typespec.tsp-server.path的作用还需要看清resolveTypeSpecServerVSExtension.cs中完整的解析顺序开发模式优先在 Debug 构建且环境变量TYPESPEC_DEVELOPMENT_MODEtrue时直接使用源码树中的compiler/entrypoints/server.js仅用于扩展开发者调试显式配置优先若配置了typespec.tsp-server.path且非空则使用该值经过变量插值与绝对路径归一化自动发现本地编译器未配置时ResolveLocalCompilerVSExtension.cs会从工作区根目录向上逐级查找node_modules/typespec/compiler目录找到即采用回退到全局命令以上都失败时回退为在 PATH 中查找tsp-server.cmd。在指定了显式路径的情况下路径的处理规则如下若路径不是以.js结尾若该路径本身是存在的文件则以.cmd命令方式启动或直接按.cmd文件处理否则将其视为编译器包目录拼接cmd/tsp-server.js若路径以.js结尾例如直接指向compiler/cmd/tsp-server.js则校验文件存在后以node.exe serverPath --stdio启动启动时会设置环境变量TYPESPEC_SKIP_COMPILER_RESOLVE1指示服务器跳过自身的编译器解析逻辑VSExtension.cs若指定的.js文件不存在会抛出TypeSpecServerNotFoundException并在 VS 中提示 Failed to activate TypeSpec language server!参见 OnServerInitializeFailedAsync。3.4 典型配置场景场景一monorepo / 嵌套项目指向子项目内的编译器{ typespec.tsp-server.path: ${workspaceFolder}/my-nested-project/node_modules/typespec/compiler }场景二直接指向tsp-server.js入口文件可选写法与目录写法等价{ typespec.tsp-server.path: ${workspaceFolder}/node_modules/typespec/compiler/cmd/tsp-server.js }场景三不配置使用自动发现若项目根目录或其任一上级目录下存在node_modules/typespec/compiler无需任何配置即可被ResolveLocalCompiler自动找到此时建议保持VSWorkspaceSettings.json为空配置或不创建该文件。四、卸载扩展卸载方式与安装对应同样有两种方式一扩展管理器卸载在 Visual Studio 的扩展Extensions→ 管理扩展Manage Extensions→ 已安装Installed中找到 TypeSpec 扩展点击卸载并重启 Visual Studio。方式二命令行卸载tsp vs uninstall该命令调用VSIXInstaller.exe /uninstall:88b9492f-c019-492c-8aeb-f325a7e4cf23vs.ts其中88b9492f-c019-492c-8aeb-f325a7e4cf23是扩展包的注册 GUID同样仅在 Windows VS 17.0 环境下可用若扩展未安装退出码1002或用户取消2005不会被当作错误处理。五、小结与排障提示安装优先使用 VS 扩展管理器从 Marketplace 安装typespec.typespecvs命令行tsp vs install可作为备选但该命令已被标记弃用且仅支持 Windows。配置在项目根目录创建.vs/VSWorkspaceSettings.json通过typespec.tsp-server.path显式指定编译器位置支持${workspaceFolder}变量插值不配置时扩展会自动向上查找node_modules/typespec/compiler。卸载扩展管理器或tsp vs uninstall均可。常见问题提示 Failed to activate TypeSpec language server!多半是typespec.tsp-server.path指向的目录下不存在cmd/tsp-server.js或路径中的变量未解析。可先确认目标路径下确有typespec/compiler包或改为绝对路径排查。修改配置不生效LoadSettingsAsync在语言客户端激活ActivateAsync时读取设置修改VSWorkspaceSettings.json后建议重启 Visual Studio 或重新加载工作区。未配置却找不到服务器检查项目与上级目录是否存在node_modules/typespec/compiler并确认其版本与扩展兼容。如需进一步阅读可参考扩展的完整说明 packages/typespec-vs/README.md或深入阅读语言客户端与路径解析实现 packages/typespec-vs/src/VSExtension.cs 与变量解析实现 packages/typespec-vs/src/VariableResolver.cs。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TypeSpec Visual Studio 扩展：安装、tsp-server 路径配置与命令行管理实战
TypeSpec Visual Studio 扩展安装、tsp-server 路径配置与命令行管理实战【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec本篇文章以 TypeSpec 官方文档中 Visual Studio 扩展一节vs.md为核心系统讲解 TypeSpec VS 扩展的安装方式、typespec.tsp-server.path工作区配置与变量插值规则以及基于tsp vsCLI 的安装/卸载管理。读完本文你将掌握在 Visual Studio 17.x 中接入 TypeSpec 语言服务、把语言服务器指向项目内typespec/compiler的完整方案并能结合本仓库源码理解其底层实现原理。一、扩展概览TypeSpec 的 Visual Studio 语言支持TypeSpec 仓库中对应 Visual Studio 的语言支持包位于 packages/typespec-vs其 package.json 将该扩展标识为 TypeSpec Language Support for Visual Studio。从 packages/typespec-vs/README.md 可以看到该扩展提供的能力包括实时诊断报告Live diagnostic reporting语法高亮Syntax highlighting代码补全Code completion代码折叠Code folding格式化Formatting悬停信息Hover info重命名重构Rename refactoring跳转到定义Go to definition这些能力本质上由 TypeSpec 语言服务器tsp-server提供Visual Studio 扩展只是作为 LSPLanguage Server Protocol 的源码可以看到扩展通过ILanguageClient接口注册名为TypeSpec的语言客户端并监听.tsp、tspconfig.yaml、.cadl、cadl-project.yaml、package.json等文件[Export(typeof(ILanguageClient))] [ContentType(typespec)] public sealed class LanguageClient : ILanguageClient { public string Name TypeSpec; public IEnumerablestring? ConfigurationSections { get; } new[] { typespec }; public IEnumerablestring FilesToWatch { get; } new[] { **/*.tsp, **/tspconfig.yaml, **/package.json, **/*.cadl, **/cadl-project.yaml }; }同时ContentDefinition 将.tsp、.cadl文件扩展名和tspconfig.yaml文件名映射到typespec内容类型从而在 VS 中触发该语言服务。二、安装扩展2.1 通过扩展管理器安装官方推荐官方文档给出的安装方式是通过Visual Studio 扩展管理器从Visual Studio Marketplace安装Marketplace 中该扩展的标识为typespec.typespecvs发布者typespec扩展名typespecvs参见 packages/typespec-vs/publishManifest.json。操作路径为Visual Studio 菜单扩展Extensions→ 管理扩展Manage Extensions→ 联机Online搜索 TypeSpec 后点击下载并安装按提示重启 Visual Studio 即可生效。2.2 通过tsp vs install命令行安装除了扩展管理器TypeSpec 编译器 CLI 也提供了对应命令。在 cli.ts 中注册了tsp vs子命令组tsp vs ├── tsp vs install # Install Visual Studio Extension. └── tsp vs uninstall # Uninstall VS Extension其实现位于 packages/compiler/src/core/cli/actions/vs.tsinstallVSExtensionvs.ts先从 Marketplace 下载 VSIX再调用VSIXInstaller.exe安装。它支持两个“非错误”退出码1001扩展已安装与2005用户取消。uninstallVSExtensionvs.ts调用VSIXInstaller.exe /uninstall:88b9492f-c019-492c-8aeb-f325a7e4cf23卸载其中 GUID 即扩展包注册的包标识见 VSExtension.cs。需要注意的适用前提均为源码可确认的事实仅支持 WindowsgetVSInstallerPath在非win32平台直接返回vs-extension-windows-only诊断vs.ts。该命令会从ProgramFiles(x86)\Microsoft Visual Studio\Installer下查找vswhere.exe与VSIXInstaller.exe。Visual Studio 版本要求通过vswhere检测的受支持版本范围为[17.0,)即 Visual Studio 2022 及更新版本vs.ts。命令已标记为弃用installVSExtension与uninstallVSExtension都调用了reportDeprecatedCommandvs.ts提示优先使用扩展管理器或 Marketplace 安装命令行路径仅作备用。三、配置 tsp-server 路径扩展安装完成后TypeSpec 语言服务器默认如何被定位以及如何强制指定其路径是配置环节的核心。3.1 配置步骤官方文档给出的配置过程分两步在项目根目录创建.vs/VSWorkspaceSettings.json文件以键值对形式写入配置例如{ typespec.tsp-server.path: ${workspaceFolder}/my-nested-project/node_modules/typespec/compiler }该配置项的作用是指定tsp-server的启动入口。从源码实现看读取该配置的逻辑位于 VSExtension.cs 的LoadSettingsAsync当存在 VS 工作区文件夹模式时通过workspace.GetSettingsManager()?.GetAggregatedSettings(SettingsTypes.Generic)读取聚合设置并读取typespec.tsp-server.path属性当打开的是解决方案.sln时扩展会自行解析 .vs/VSWorkspaceSettings.json 文件将其中所有字符串类型的键值对读入配置字典非字符串值会被过滤掉参见 ReadSettingsFromJson。说明typespec.tsp-server.path指向的是typespec/compiler包的根目录例如node_modules/typespec/compiler而不是某个单独的二进制文件。扩展在解析时会在此基础上拼接cmd/tsp-server.js作为实际入口见下文 3.3 节。3.2 变量插值规则TypeSpec 支持在配置值中使用${name}形式的变量插值。官方文档示例中的${workspaceFolder}对应 Visual Studio 工作区的根目录。插值的底层实现位于 VariableResolver.cs核心逻辑如下private const string VARIABLE_REGEXP \$\{(.*?)\}; public static string ResolveVariables(string value, IDictionarystring, string variables) { return Regex.Replace(value, VARIABLE_REGEXP, (match) { var group match.Groups[1]; if (group ! null variables.TryGetValue(group.Value, out var variable)) { return variable; } return match.Value; // 未注册的变量保持原样 }); }从中可以确认两个细节插值语法为\$\{(.*?)\}即${变量名}未注册的变量不会被替换会原样保留在路径字符串中。因此在使用自定义变量前务必确认该变量已在 VS 工作区上下文中注册当前可用的内置变量为workspaceFolder对应工作区根目录在解决方案模式下对应.sln所在目录参见 GetSolutionFolderAsync。插值在路径解析流程中的位置见 VSExtension.cs扩展先构造variables字典仅注册workspaceFolder再调用VariableResolver.ResolveVariables完成替换最后通过Path.GetFullPath归一化为绝对路径。3.3 服务器路径的解析优先级理解typespec.tsp-server.path的作用还需要看清resolveTypeSpecServerVSExtension.cs中完整的解析顺序开发模式优先在 Debug 构建且环境变量TYPESPEC_DEVELOPMENT_MODEtrue时直接使用源码树中的compiler/entrypoints/server.js仅用于扩展开发者调试显式配置优先若配置了typespec.tsp-server.path且非空则使用该值经过变量插值与绝对路径归一化自动发现本地编译器未配置时ResolveLocalCompilerVSExtension.cs会从工作区根目录向上逐级查找node_modules/typespec/compiler目录找到即采用回退到全局命令以上都失败时回退为在 PATH 中查找tsp-server.cmd。在指定了显式路径的情况下路径的处理规则如下若路径不是以.js结尾若该路径本身是存在的文件则以.cmd命令方式启动或直接按.cmd文件处理否则将其视为编译器包目录拼接cmd/tsp-server.js若路径以.js结尾例如直接指向compiler/cmd/tsp-server.js则校验文件存在后以node.exe serverPath --stdio启动启动时会设置环境变量TYPESPEC_SKIP_COMPILER_RESOLVE1指示服务器跳过自身的编译器解析逻辑VSExtension.cs若指定的.js文件不存在会抛出TypeSpecServerNotFoundException并在 VS 中提示 Failed to activate TypeSpec language server!参见 OnServerInitializeFailedAsync。3.4 典型配置场景场景一monorepo / 嵌套项目指向子项目内的编译器{ typespec.tsp-server.path: ${workspaceFolder}/my-nested-project/node_modules/typespec/compiler }场景二直接指向tsp-server.js入口文件可选写法与目录写法等价{ typespec.tsp-server.path: ${workspaceFolder}/node_modules/typespec/compiler/cmd/tsp-server.js }场景三不配置使用自动发现若项目根目录或其任一上级目录下存在node_modules/typespec/compiler无需任何配置即可被ResolveLocalCompiler自动找到此时建议保持VSWorkspaceSettings.json为空配置或不创建该文件。四、卸载扩展卸载方式与安装对应同样有两种方式一扩展管理器卸载在 Visual Studio 的扩展Extensions→ 管理扩展Manage Extensions→ 已安装Installed中找到 TypeSpec 扩展点击卸载并重启 Visual Studio。方式二命令行卸载tsp vs uninstall该命令调用VSIXInstaller.exe /uninstall:88b9492f-c019-492c-8aeb-f325a7e4cf23vs.ts其中88b9492f-c019-492c-8aeb-f325a7e4cf23是扩展包的注册 GUID同样仅在 Windows VS 17.0 环境下可用若扩展未安装退出码1002或用户取消2005不会被当作错误处理。五、小结与排障提示安装优先使用 VS 扩展管理器从 Marketplace 安装typespec.typespecvs命令行tsp vs install可作为备选但该命令已被标记弃用且仅支持 Windows。配置在项目根目录创建.vs/VSWorkspaceSettings.json通过typespec.tsp-server.path显式指定编译器位置支持${workspaceFolder}变量插值不配置时扩展会自动向上查找node_modules/typespec/compiler。卸载扩展管理器或tsp vs uninstall均可。常见问题提示 Failed to activate TypeSpec language server!多半是typespec.tsp-server.path指向的目录下不存在cmd/tsp-server.js或路径中的变量未解析。可先确认目标路径下确有typespec/compiler包或改为绝对路径排查。修改配置不生效LoadSettingsAsync在语言客户端激活ActivateAsync时读取设置修改VSWorkspaceSettings.json后建议重启 Visual Studio 或重新加载工作区。未配置却找不到服务器检查项目与上级目录是否存在node_modules/typespec/compiler并确认其版本与扩展兼容。如需进一步阅读可参考扩展的完整说明 packages/typespec-vs/README.md或深入阅读语言客户端与路径解析实现 packages/typespec-vs/src/VSExtension.cs 与变量解析实现 packages/typespec-vs/src/VariableResolver.cs。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考