Skip to content

Commit cd3adb9

Browse files
authored
docs: update README and CHANGELOG for recent SDK features (#44)
- Add VS Project and Item Templates section with auto-discovery docs - Document cross-project template references via VsixTemplateReference - Add NuGet Central Package Management (CPM) compatibility section - Update Auto-Inclusion section with imagemanifest and ContentManifest.json - Add new properties to Configuration table (template-related) - Update Disabling Auto-Inclusion with new disable options - Add Unreleased section to CHANGELOG with all recent changes
1 parent 9fbc996 commit cd3adb9

File tree

2 files changed

+102
-0
lines changed

2 files changed

+102
-0
lines changed

CHANGELOG.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### Added
11+
12+
- Template support for project and item templates with auto-discovery in `ProjectTemplates/` and `ItemTemplates/` folders
13+
- Auto-injection of `<Content>` entries into vsixmanifest for discovered templates (`AutoInjectVsixTemplateContent` property)
14+
- Cross-project template references via `VsixTemplateReference` item type
15+
- Auto-inclusion of `.imagemanifest` files as `ImageManifest` items
16+
- Auto-inclusion of `ContentManifest.json` files as `Content` items
17+
- NuGet Central Package Management (CPM) support
18+
- Build validation warnings for missing manifest Content entries (VSIXSDK011-014)
19+
20+
### Changed
21+
22+
- Removed implicit `PackageReference` for `Microsoft.VSSDK.BuildTools` - users must now explicitly add this reference
23+
1024
## [0.3.0] - 2025-12-30
1125

1226
### Added

README.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -296,6 +296,8 @@ The SDK automatically includes common VSIX files:
296296
- 📄 `*.vsct` files as `VSCTCompile` items
297297
- 📄 `VSPackage.resx` files with proper metadata
298298
- 📄 `source.extension.vsixmanifest` as an `AdditionalFile` for source generators
299+
- 📄 `*.imagemanifest` files as `ImageManifest` items (for VS Image Service)
300+
- 📄 `ContentManifest.json` files as `Content` items (for VS content registration)
299301

300302
### 🐛 F5 Debugging
301303

@@ -307,6 +309,59 @@ Press F5 to launch the Visual Studio Experimental Instance with your extension l
307309

308310
Extensions are only deployed to the Experimental Instance when building inside Visual Studio. This prevents errors when building from the command line.
309311

312+
### 📦 VS Project and Item Templates
313+
314+
The SDK provides comprehensive support for including Visual Studio project and item templates in your VSIX package.
315+
316+
#### Auto-Discovery
317+
318+
Place templates in `ProjectTemplates/` or `ItemTemplates/` folders and they'll be automatically discovered and packaged:
319+
320+
```
321+
MyExtension/
322+
├── ProjectTemplates/
323+
│ └── MyProjectTemplate/
324+
│ ├── MyProject.csproj
325+
│ ├── Class1.cs
326+
│ └── MyTemplate.vstemplate
327+
├── ItemTemplates/
328+
│ └── MyItemTemplate/
329+
│ ├── MyItem.cs
330+
│ └── MyItem.vstemplate
331+
└── source.extension.vsixmanifest
332+
```
333+
334+
The SDK automatically:
335+
1. Discovers `.vstemplate` files in these folders
336+
2. Injects the required `<Content>` entries into the manifest (via intermediate file)
337+
3. Includes all template files in the VSIX
338+
339+
#### Cross-Project Template References
340+
341+
Reference templates from other SDK-style projects using `VsixTemplateReference`:
342+
343+
```xml
344+
<ItemGroup>
345+
<VsixTemplateReference Include="..\MyTemplateProject\MyTemplateProject.csproj"
346+
TemplateType="Project"
347+
TemplatePath="Templates\MyProjectTemplate" />
348+
</ItemGroup>
349+
```
350+
351+
This is useful when the VSIX Manifest Designer cannot enumerate SDK-style projects.
352+
353+
#### Disabling Auto-Injection
354+
355+
If you prefer to manage manifest Content entries manually:
356+
357+
```xml
358+
<PropertyGroup>
359+
<AutoInjectVsixTemplateContent>false</AutoInjectVsixTemplateContent>
360+
</PropertyGroup>
361+
```
362+
363+
When disabled, build warnings (VSIXSDK011, VSIXSDK012) will alert you if templates are discovered but the manifest lacks the corresponding `<Content>` entries.
364+
310365
## ⚙️ Configuration
311366

312367
### Properties
@@ -318,6 +373,10 @@ Extensions are only deployed to the Experimental Instance when building inside V
318373
| `GeneratePkgDefFile` | `true` | Generate .pkgdef registration file |
319374
| `DeployExtension` | `true`* | Deploy to experimental instance |
320375
| `EnableDefaultVsixItems` | `true` | Auto-include VSIX-related files |
376+
| `EnableDefaultVsixTemplateItems` | `true` | Auto-discover templates in ProjectTemplates/ItemTemplates folders |
377+
| `AutoInjectVsixTemplateContent` | `true` | Auto-inject Content entries into manifest for discovered templates |
378+
| `VsixProjectTemplatesFolder` | `ProjectTemplates` | Folder for project templates |
379+
| `VsixItemTemplatesFolder` | `ItemTemplates` | Folder for item templates |
321380
| `EmitCompilerGeneratedFiles` | `true` | Write generated source files to disk |
322381
| `CompilerGeneratedFilesOutputPath` | `Generated/` | Location for generated source files |
323382

@@ -339,6 +398,9 @@ Or disable specific categories:
339398
<PropertyGroup>
340399
<EnableDefaultVsctItems>false</EnableDefaultVsctItems>
341400
<EnableDefaultVSPackageResourceItems>false</EnableDefaultVSPackageResourceItems>
401+
<EnableDefaultImageManifestItems>false</EnableDefaultImageManifestItems>
402+
<EnableDefaultContentManifestItems>false</EnableDefaultContentManifestItems>
403+
<EnableDefaultVsixTemplateItems>false</EnableDefaultVsixTemplateItems>
342404
</PropertyGroup>
343405
```
344406

@@ -355,6 +417,32 @@ Or disable specific categories:
355417
- Visual Studio 2022 or later
356418
- .NET Framework 4.7.2+ target framework
357419

420+
### NuGet Central Package Management (CPM)
421+
422+
The SDK is fully compatible with [NuGet Central Package Management](https://learn.microsoft.com/nuget/consume-packages/central-package-management). When using CPM, define your package versions in `Directory.Packages.props`:
423+
424+
```xml
425+
<!-- Directory.Packages.props -->
426+
<Project>
427+
<PropertyGroup>
428+
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
429+
</PropertyGroup>
430+
<ItemGroup>
431+
<PackageVersion Include="Microsoft.VisualStudio.SDK" Version="17.*" />
432+
<PackageVersion Include="Microsoft.VSSDK.BuildTools" Version="17.*" />
433+
</ItemGroup>
434+
</Project>
435+
```
436+
437+
Then reference packages without versions in your project:
438+
439+
```xml
440+
<ItemGroup>
441+
<PackageReference Include="Microsoft.VisualStudio.SDK" />
442+
<PackageReference Include="Microsoft.VSSDK.BuildTools" PrivateAssets="all" />
443+
</ItemGroup>
444+
```
445+
358446
## 🏗️ Building from Source
359447

360448
```bash

0 commit comments

Comments
 (0)