From 5004f3eca655dabe0116ce8957649f5af6ee7cfe Mon Sep 17 00:00:00 2001 From: "Calvin A. Allen" Date: Tue, 6 Jan 2026 13:33:58 -0500 Subject: [PATCH 1/2] feat(sdk): add template support for project and item templates Add MSBuild-based support for including VS project and item templates in VSIX packages, bypassing the broken VSIX Manifest Designer. New item types: - VsixProjectTemplate: folder-based project templates - VsixItemTemplate: folder-based item templates - VsixTemplateZip: pre-built template zip files - VsixTemplateReference: reference templates from another project Features: - Auto-discovery of templates in ProjectTemplates/ and ItemTemplates/ - Auto-zip folder-based templates during build - Hook into VSSDK's GetVsixSourceItems for VSIX inclusion - Build warnings for missing manifest Content entries (VSIXSDK010-014) Includes documentation in docs/templates.md. Closes #21 Closes #22 --- docs/templates.md | 230 +++++++++++++++ .../Sdk/Sdk.Vsix.Templates.props | 74 +++++ .../Sdk/Sdk.Vsix.Templates.targets | 271 ++++++++++++++++++ .../Sdk/Sdk.Vsix.props | 3 + .../Sdk/Sdk.Vsix.targets | 3 + 5 files changed, 581 insertions(+) create mode 100644 docs/templates.md create mode 100644 src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.props create mode 100644 src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.targets diff --git a/docs/templates.md b/docs/templates.md new file mode 100644 index 0000000..7fef526 --- /dev/null +++ b/docs/templates.md @@ -0,0 +1,230 @@ +# Template Support + +This document explains how to include Visual Studio project templates and item templates in your VSIX extension using CodingWithCalvin.VsixSdk. + +## Background + +The built-in VSIX Manifest Designer in Visual Studio cannot enumerate SDK-style projects when adding template assets. This is because the designer uses legacy DTE extenders that are registered for the old project system, not the Common Project System (CPS) used by SDK-style projects. + +Additionally, SDK-style projects don't define the `TemplateProjectOutputGroup` and `ItemTemplateOutputGroup` MSBuild output groups that VSSDK expects for template assets. + +This SDK provides MSBuild-based template support that bypasses these limitations entirely. + +## Item Types + +The SDK provides four item types for including templates: + +| Item Type | Description | +|-----------|-------------| +| `VsixProjectTemplate` | A folder containing a `.vstemplate` file for a project template | +| `VsixItemTemplate` | A folder containing a `.vstemplate` file for an item template | +| `VsixTemplateZip` | A pre-built template zip file | +| `VsixTemplateReference` | Reference a template folder from another project | + +## Auto-Discovery + +By default, the SDK automatically discovers templates in your project: + +- **Project templates**: Any subfolder in `ProjectTemplates/` containing a `.vstemplate` file +- **Item templates**: Any subfolder in `ItemTemplates/` containing a `.vstemplate` file + +### Example Project Structure + +``` +MyExtension/ + MyExtension.csproj + source.extension.vsixmanifest + ProjectTemplates/ + MyProjectTemplate/ + MyProjectTemplate.vstemplate + MyProject.csproj + Class1.cs + ItemTemplates/ + MyItemTemplate/ + MyItemTemplate.vstemplate + MyClass.cs +``` + +With this structure, no additional configuration is needed. The SDK will: +1. Find the templates automatically +2. Zip each template folder during build +3. Include the zips in the VSIX at `ProjectTemplates/` and `ItemTemplates/` + +### Disabling Auto-Discovery + +To disable automatic template discovery: + +```xml + + false + +``` + +### Changing Default Folders + +To use different folder names: + +```xml + + Templates\Projects + Templates\Items + +``` + +## Manual Template Configuration + +### Folder-Based Templates + +If your templates are in non-standard locations, add them explicitly: + +```xml + + + + +``` + +### Pre-Built Template Zips + +If you have pre-built template zip files: + +```xml + + + + +``` + +### Template References + +To include a template from another project in your solution: + +```xml + + + +``` + +The `TemplatePath` is relative to the referenced project's directory. + +## Manifest Configuration + +Visual Studio requires `` entries in your `.vsixmanifest` to register templates. Add these to your manifest: + +```xml + + + + +``` + +The SDK will emit warnings if you have templates defined but missing manifest entries: +- **VSIXSDK011**: Project templates defined but no `` in manifest +- **VSIXSDK012**: Item templates defined but no `` in manifest + +## Target Subfolders + +To organize templates into subfolders within the VSIX: + +```xml + + + + + + + +``` + +## Complete Example + +### Project File + +```xml + + + + 1.0.0 + + + + + + + + +``` + +### Manifest File + +```xml + + + + + My Extension + Extension with templates + + + + amd64 + + + + + + + +``` + +### Template File (.vstemplate) + +```xml + + + + My Project Template + A sample project template + __TemplateIcon.ico + CSharp + MyProject + true + + + + Class1.cs + + + +``` + +## Validation Warnings + +| Code | Description | +|------|-------------| +| VSIXSDK010 | `VsixTemplateZip` item missing `TemplateType` metadata | +| VSIXSDK011 | Project templates defined but no `` in manifest | +| VSIXSDK012 | Item templates defined but no `` in manifest | +| VSIXSDK013 | `VsixTemplateReference` item missing `TemplateType` metadata | +| VSIXSDK014 | `VsixTemplateReference` item missing `TemplatePath` metadata | + +## Troubleshooting + +### Templates not appearing in Visual Studio + +1. Ensure your manifest has the appropriate `` entries +2. Check that the template zip files are included in the VSIX (open the .vsix as a zip) +3. Verify the `.vstemplate` file has correct `` or `` +4. Reset the Visual Studio template cache: delete `%LocalAppData%\Microsoft\VisualStudio\\ComponentModelCache` + +### Build errors about missing template folders + +Ensure the template folder exists and contains a `.vstemplate` file. For `VsixTemplateReference`, verify the `TemplatePath` is correct relative to the referenced project. + +### Templates in wrong location in VSIX + +Check the `TargetSubPath` metadata if you're using custom paths. By default, templates are placed directly in `ProjectTemplates/` or `ItemTemplates/`. diff --git a/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.props b/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.props new file mode 100644 index 0000000..231eb4c --- /dev/null +++ b/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.props @@ -0,0 +1,74 @@ + + + + + + true + + + ProjectTemplates + ItemTemplates + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.targets b/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.targets new file mode 100644 index 0000000..e1ce911 --- /dev/null +++ b/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.targets @@ -0,0 +1,271 @@ + + + + + + <_VsixTemplateIntermediateOutputPath>$(IntermediateOutputPath)VsixTemplates\ + + + + + + <_DiscoveredProjectTemplateFiles Include="$(VsixProjectTemplatesFolder)\**\*.vstemplate" + Condition="Exists('$(MSBuildProjectDirectory)\$(VsixProjectTemplatesFolder)')" + Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" /> + + + + + + + + + <_DiscoveredItemTemplateFiles Include="$(VsixItemTemplatesFolder)\**\*.vstemplate" + Condition="Exists('$(MSBuildProjectDirectory)\$(VsixItemTemplatesFolder)')" + Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" /> + + + + + + + + $(DefaultItemExcludes);$(VsixProjectTemplatesFolder)\** + $(DefaultItemExcludes);$(VsixItemTemplatesFolder)\** + + + + + + + + <_TemplateFolderName>$([System.IO.Path]::GetFileName('%(Identity)')) + <_ZipFileName>%(VsixProjectTemplate._TemplateFolderName).zip + <_ZipOutputPath>$(_VsixTemplateIntermediateOutputPath)ProjectTemplates\%(VsixProjectTemplate.TargetSubPath) + + + + + <_TemplateFolderName>$([System.IO.Path]::GetFileName('%(Identity)')) + <_ZipFileName>%(VsixItemTemplate._TemplateFolderName).zip + <_ZipOutputPath>$(_VsixTemplateIntermediateOutputPath)ItemTemplates\%(VsixItemTemplate.TargetSubPath) + + + + + <_ReferencedProjectDir>$([System.IO.Path]::GetDirectoryName('%(Identity)')) + <_FullTemplatePath>%(VsixTemplateReference._ReferencedProjectDir)\%(VsixTemplateReference.TemplatePath) + <_TemplateFolderName>$([System.IO.Path]::GetFileName('%(VsixTemplateReference.TemplatePath)')) + <_ZipFileName>%(VsixTemplateReference._TemplateFolderName).zip + <_ZipOutputPath Condition="'%(VsixTemplateReference.TemplateType)' == 'Project'">$(_VsixTemplateIntermediateOutputPath)ProjectTemplates\%(VsixTemplateReference.TargetSubPath) + <_ZipOutputPath Condition="'%(VsixTemplateReference.TemplateType)' == 'Item'">$(_VsixTemplateIntermediateOutputPath)ItemTemplates\%(VsixTemplateReference.TargetSubPath) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ProjectTemplates\%(VsixProjectTemplate.TargetSubPath) + false + ProjectTemplates + + + + + ItemTemplates\%(VsixItemTemplate.TargetSubPath) + false + ItemTemplates + + + + + ProjectTemplates\%(VsixTemplateZip.TargetSubPath) + false + ProjectTemplates + + + + + ItemTemplates\%(VsixTemplateZip.TargetSubPath) + false + ItemTemplates + + + + + ProjectTemplates\%(VsixTemplateReference.TargetSubPath) + false + ProjectTemplates + + + + + ItemTemplates\%(VsixTemplateReference.TargetSubPath) + false + ItemTemplates + + + + + + + + + + + + + + + + + + + + + + + + <_HasProjectTemplates Condition="'@(VsixProjectTemplate)' != ''">true + <_HasProjectTemplates Condition="'@(VsixTemplateReference->WithMetadataValue('TemplateType', 'Project'))' != ''">true + <_HasItemTemplates Condition="'@(VsixItemTemplate)' != ''">true + <_HasItemTemplates Condition="'@(VsixTemplateReference->WithMetadataValue('TemplateType', 'Item'))' != ''">true + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.props b/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.props index 2db6af2..0b6b31b 100644 --- a/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.props +++ b/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.props @@ -5,6 +5,9 @@ VSIX-specific properties. Can be imported standalone or as part of the full SDK. --> + + + + + + + + + net472 + 1.0.0 + SampleExtensionWithTemplates + SampleExtensionWithTemplates + + + + + + + diff --git a/samples/SampleExtensionWithTemplates/SampleExtensionWithTemplatesPackage.cs b/samples/SampleExtensionWithTemplates/SampleExtensionWithTemplatesPackage.cs new file mode 100644 index 0000000..952f049 --- /dev/null +++ b/samples/SampleExtensionWithTemplates/SampleExtensionWithTemplatesPackage.cs @@ -0,0 +1,35 @@ +using System; +using System.Runtime.InteropServices; +using System.Threading; +using Microsoft.VisualStudio.Shell; +using Task = System.Threading.Tasks.Task; + +namespace SampleExtensionWithTemplates +{ + /// + /// This is the class that implements the package exposed by this assembly. + /// + [PackageRegistration(UseManagedResourcesOnly = true, AllowsBackgroundLoading = true)] + [Guid(PackageGuidString)] + public sealed class SampleExtensionWithTemplatesPackage : AsyncPackage + { + /// + /// SampleExtensionWithTemplatesPackage GUID string. + /// + public const string PackageGuidString = "b2c3d4e5-f6a7-8901-bcde-f23456789012"; + + /// + /// Initialization of the package; this method is called right after the package is sited. + /// + protected override async Task InitializeAsync(CancellationToken cancellationToken, IProgress progress) + { + await base.InitializeAsync(cancellationToken, progress); + + // When initialized asynchronously, switch to the main thread before accessing VS services + await JoinableTaskFactory.SwitchToMainThreadAsync(cancellationToken); + + // This extension provides project and item templates + // Templates are automatically discovered from ProjectTemplates/ and ItemTemplates/ folders + } + } +} diff --git a/samples/SampleExtensionWithTemplates/source.extension.vsixmanifest b/samples/SampleExtensionWithTemplates/source.extension.vsixmanifest new file mode 100644 index 0000000..21db316 --- /dev/null +++ b/samples/SampleExtensionWithTemplates/source.extension.vsixmanifest @@ -0,0 +1,34 @@ + + + + + Sample Extension With Templates + A sample Visual Studio extension demonstrating template support with CodingWithCalvin.VsixSdk + https://github.com/CodingWithCalvin/VsixSdk + sample, templates, vsix + + + + amd64 + + + amd64 + + + amd64 + + + + + + + + + + + + + + + + diff --git a/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.targets b/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.targets index e1ce911..416585b 100644 --- a/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.targets +++ b/src/CodingWithCalvin.VsixSdk/Sdk/Sdk.Vsix.Templates.targets @@ -15,34 +15,32 @@ - + - <_DiscoveredProjectTemplateFiles Include="$(VsixProjectTemplatesFolder)\**\*.vstemplate" - Condition="Exists('$(MSBuildProjectDirectory)\$(VsixProjectTemplatesFolder)')" - Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" /> - - - - + + <_DiscoveredProjectTemplateFiles Include="$(MSBuildProjectDirectory)\$(VsixProjectTemplatesFolder)\**\*.vstemplate" + Condition="Exists('$(MSBuildProjectDirectory)\$(VsixProjectTemplatesFolder)')" /> + <_DiscoveredItemTemplateFiles Include="$(MSBuildProjectDirectory)\$(VsixItemTemplatesFolder)\**\*.vstemplate" + Condition="Exists('$(MSBuildProjectDirectory)\$(VsixItemTemplatesFolder)')" /> + - - - - <_DiscoveredItemTemplateFiles Include="$(VsixItemTemplatesFolder)\**\*.vstemplate" - Condition="Exists('$(MSBuildProjectDirectory)\$(VsixItemTemplatesFolder)')" - Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" /> + + + + + <_TemplateFolderName>%(_DiscoveredProjectTemplateFiles.Filename) + + - - - + + + <_TemplateFolderName>%(_DiscoveredItemTemplateFiles.Filename) + + + - + - + + - <_TemplateFolderName>$([System.IO.Path]::GetFileName('%(Identity)')) <_ZipFileName>%(VsixProjectTemplate._TemplateFolderName).zip <_ZipOutputPath>$(_VsixTemplateIntermediateOutputPath)ProjectTemplates\%(VsixProjectTemplate.TargetSubPath) - + - <_TemplateFolderName>$([System.IO.Path]::GetFileName('%(Identity)')) <_ZipFileName>%(VsixItemTemplate._TemplateFolderName).zip <_ZipOutputPath>$(_VsixTemplateIntermediateOutputPath)ItemTemplates\%(VsixItemTemplate.TargetSubPath) @@ -146,7 +143,6 @@ Condition="'@(VsixProjectTemplate)' != ''"> ProjectTemplates\%(VsixProjectTemplate.TargetSubPath) false - ProjectTemplates @@ -154,7 +150,6 @@ Condition="'@(VsixItemTemplate)' != ''"> ItemTemplates\%(VsixItemTemplate.TargetSubPath) false - ItemTemplates @@ -162,7 +157,6 @@ Condition="'@(VsixTemplateZip)' != '' and '%(VsixTemplateZip.TemplateType)' == 'Project'"> ProjectTemplates\%(VsixTemplateZip.TargetSubPath) false - ProjectTemplates @@ -170,7 +164,6 @@ Condition="'@(VsixTemplateZip)' != '' and '%(VsixTemplateZip.TemplateType)' == 'Item'"> ItemTemplates\%(VsixTemplateZip.TargetSubPath) false - ItemTemplates @@ -178,7 +171,6 @@ Condition="'@(VsixTemplateReference)' != '' and '%(VsixTemplateReference.TemplateType)' == 'Project'"> ProjectTemplates\%(VsixTemplateReference.TargetSubPath) false - ProjectTemplates @@ -186,7 +178,6 @@ Condition="'@(VsixTemplateReference)' != '' and '%(VsixTemplateReference.TemplateType)' == 'Item'"> ItemTemplates\%(VsixTemplateReference.TargetSubPath) false - ItemTemplates