Visual Studio 模板详解

Visual Studio模板分为项目模板（Project Template） 、项模板（Item Template） 两类；本质是打包好的代码骨架 + .vstemplate 清单，新建项目/新建项时自动解压、替换变量，一次性生成文件、引用、基础代码、项目配置，避免重复写样板代码。

一、两类模板核心区别

1）项目模板 Project Template

入口：文件 → 新建 → 项目 作用：一次性创建完整项目 （.csproj/.vbproj/.vcxproj + 多源码文件、文件夹结构、程序集引用、NuGet包、项目属性）常见内置模板：控制台应用、类库、ASP.NET Core WebApi、WinForms、WPF、单元测试项目等。

2）项模板 Item Template

入口：项目右键 → 添加 → 新建项作用：在已有项目内新增单个/一组文件（如自定义实体类、仓储类、控制器、HTML页面）内置示例：C#类、接口、枚举、XML、CSS。

底层结构：所有模板打包为 ZIP压缩包 ，包内必须包含 .vstemplate XML清单 + 业务文件；放到指定目录后VS识别展示。

二、模板目录位置（VS2019/2022）

替换<Version>为 2019 / 2022

项目模板目录： %USERPROFILE%\Documents\Visual Studio <Version>\Templates\ProjectTemplates
项模板目录： %USERPROFILE%\Documents\Visual Studio <Version>\Templates\ItemTemplates

⚠️ VS2017+ 重要变化：不再自动扫描文件夹内zip 。简单导出模板向导生成的zip仍可直接放上面目录；企业级分发模板需要 VSIX扩展 + 模板清单文件，仅复制zip不再生效。

三、.vstemplate 核心清单解析

.vstemplate 是模板的"配置文件"，控制界面名称、描述、图标、文件列表、参数替换。

最简项目模板示例：

xml 复制代码

<VSTemplate Type="Project" Version="3.0.0" xmlns="[http://schemas.microsoft.com/developer/vstemplate/2005](http://schemas.microsoft.com/developer/vstemplate/2005)">
  <TemplateData>
    <Name>我的C#类库模板</Name>
    <Description>预配置通用引用、基础目录结构</Description>
    <Icon>icon.ico</Icon>
    <ProjectType>CSharp</ProjectType>
  </TemplateData>
  <TemplateContent>
    <Project File="TemplateProject.csproj" ReplaceParameters="true">
      <ProjectItem ReplaceParameters="true">Class1.cs</ProjectItem>
    </Project>
  </TemplateContent>
</VSTemplate>

Type="Project"：项目模板；Type="Item"：项模板
ReplaceParameters="true"：开启文件内变量替换
TemplateData：控制新建项目对话框上的显示信息
TemplateContent：定义模板包含哪些文件、项目结构

四、模板内置替换参数（最常用）

新建项目时VS自动把这些占位符替换成用户输入的值，文件必须开启ReplaceParameters才能生效

参数	含义
$projectnameprojectname$ projectname	用户输入的项目名称
$safeprojectnamesafeprojectname$ safeprojectname	安全项目名（自动过滤非法字符，推荐用于命名空间）
$solutionnamesolutionname$ solutionname	解决方案名称
$rootnamespacerootnamespace$ rootnamespace	默认根命名空间（C#）
$usernameusername$ username	当前Windows用户名
$datedate$ date	当前日期

示例代码文件：

ruby 复制代码

namespace $safeprojectname$
{
    public class Demo
    {
    }
}

五、快速创建自定义模板（向导方式，推荐日常使用）

1. 项目模板导出

先手动建好一个样板项目：写好目录、引用、基础代码、NuGet包
菜单：项目 → 导出模板
模板类型：选择【项目模板】→ 下一步
填写模板名称、描述、图标
勾选【自动将模板导入Visual Studio】，完成
VS自动生成zip包并放入ProjectTemplates目录；重启VS即可在新建项目界面看到

2. 项模板导出

在现有项目中准备好样板cs文件
项目 → 导出模板 → 选择【项模板】
选中要导出的文件、勾选需要携带的程序集引用
填写名称图标，自动导入；重启VS，在添加新项窗口出现

缺点：向导方式只适合简单模板；复杂场景（动态弹窗、运行时逻辑、自动安装NuGet、多项目解决方案模板）要用 VSIX + IWizard自定义向导

六、进阶能力

1）模板内置自动安装NuGet包

在 .vstemplate 的 <TemplateContent> 内增加 <NuGetPackage> 节点，新建项目时自动安装指定Nuget，无需手动还原。

2）IWizard 自定义向导（高级）

实现 Microsoft.VisualStudio.TemplateWizard.IWizard 接口，可以：

弹出自定义窗口收集用户输入
根据输入动态增删文件、修改内容
动态修改项目引用、执行初始化脚本> > 依赖 Visual Studio SDK，项目类型为VSIX，用于团队/公司统一脚手架分发。

3）多项目解决方案模板

一个模板一次性生成包含多个项目的解决方案（如API + 实体类库 + 单元测试），适合DDD、分层架构脚手架。

七、常见坑

导出模板后看不到

VS2017以后：简单向导导出模板可以直接使用；手动zip包注意路径、不要嵌套文件夹，zip根目录直接放.vstemplate，不要套一层子文件夹。
必须重启VS才加载新模板。

2.变量不生效：忘记写 ReplaceParameters="true"

3.中文乱码：模板源码文件保存为UTF-8。

4.NuGet包版本固定：模板写死包版本，升级需要重新导出模板。

5.自定义模板不能跨语言混用（C#模板不能在C++项目里显示）。

八、使用场景建议

个人开发：导出模板，统一基础类、日志、全局配置，减少重复编码
团队规范：统一项目目录结构、命名空间、公共引用，强制代码脚手架
企业级：VSIX打包分发，统一框架版本、自动引入内部Nuget包，配合IWizard做初始化