Skip to content

Commit 6172d67

Browse files
CalvinAllenCalvinAllen
committed
docs: refresh README with emojis and reorganized sections
- Add emojis to all section headers for visual appeal - Reorganize 'Migrating from Legacy Projects' before 'Manual Setup' - Add bullet emojis for feature highlights - Improve overall readability
1 parent 746bfdb commit 6172d67

1 file changed

Lines changed: 135 additions & 133 deletions

File tree

‎README.md‎

Lines changed: 135 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,21 @@
33
[![NuGet](https://img.shields.io/nuget/v/CodingWithCalvin.VsixSdk.svg)](https://www.nuget.org/packages/CodingWithCalvin.VsixSdk)
44
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
55

6-
An MSBuild SDK that brings modern SDK-style `.csproj` files to Visual Studio extension development. No more XML soup!
6+
An MSBuild SDK that brings modern SDK-style `.csproj` files to Visual Studio extension development. No more XML soup! 🎉
77

8-
## Why This Exists
8+
## 💡 Why This Exists
99

1010
Visual Studio extension projects are stuck in the past. They still use the old, verbose project format while the rest of .NET has moved on to clean SDK-style projects.
1111

1212
**This SDK fixes that.**
1313

14-
Write clean `.csproj` files. Get source generators for compile-time constants. Ship fully functional VSIX packages.
14+
✨ Write clean `.csproj` files
15+
✨ Get source generators for compile-time constants
16+
✨ Ship fully functional VSIX packages
1517

16-
## Getting Started
18+
## 🚀 Getting Started
1719

18-
### Using the Template (Recommended)
20+
### 📦 Using the Template (Recommended)
1921

2022
The easiest way to create a new VSIX project is with the dotnet template:
2123

@@ -57,7 +59,117 @@ dotnet new vsix -n MyExtension \
5759
--tags "productivity, tools, editor"
5860
```
5961

60-
### Manual Setup
62+
### 🔄 Migrating from Legacy Projects
63+
64+
Have an existing non-SDK style VSIX project? Here's how to modernize it:
65+
66+
#### Step 1: Back Up Your Project
67+
68+
Before making changes, ensure your project is committed to source control or backed up.
69+
70+
#### Step 2: Replace the .csproj Content
71+
72+
Replace your entire `.csproj` file with the SDK-style format:
73+
74+
**Before (Legacy):**
75+
```xml
76+
<?xml version="1.0" encoding="utf-8"?>
77+
<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
78+
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('...')" />
79+
<PropertyGroup>
80+
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
81+
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
82+
<ProjectGuid>{YOUR-GUID}</ProjectGuid>
83+
<OutputType>Library</OutputType>
84+
<AppDesignerFolder>Properties</AppDesignerFolder>
85+
<RootNamespace>MyExtension</RootNamespace>
86+
<AssemblyName>MyExtension</AssemblyName>
87+
<TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>
88+
<!-- ... many more lines ... -->
89+
</PropertyGroup>
90+
<!-- ... hundreds of lines of XML ... -->
91+
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
92+
<Import Project="$(VSToolsPath)\VSSDK\Microsoft.VsSDK.targets" Condition="'$(VSToolsPath)' != ''" />
93+
</Project>
94+
```
95+
96+
**After (SDK-style):**
97+
```xml
98+
<Project Sdk="CodingWithCalvin.VsixSdk/1.0.0">
99+
100+
<PropertyGroup>
101+
<TargetFramework>net472</TargetFramework>
102+
<RootNamespace>MyExtension</RootNamespace>
103+
<AssemblyName>MyExtension</AssemblyName>
104+
</PropertyGroup>
105+
106+
<ItemGroup>
107+
<PackageReference Include="Microsoft.VisualStudio.SDK" Version="17.*" />
108+
<PackageReference Include="Microsoft.VSSDK.BuildTools" Version="17.*" PrivateAssets="all" />
109+
</ItemGroup>
110+
111+
</Project>
112+
```
113+
114+
#### Step 3: Update the VSIX Manifest for VS 2022+
115+
116+
Add `<ProductArchitecture>amd64</ProductArchitecture>` to each `InstallationTarget`:
117+
118+
```xml
119+
<Installation>
120+
<InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0, 19.0)">
121+
<ProductArchitecture>amd64</ProductArchitecture>
122+
</InstallationTarget>
123+
<!-- Repeat for Professional, Enterprise if needed -->
124+
</Installation>
125+
```
126+
127+
#### Step 4: Remove Unnecessary Files
128+
129+
Delete these files if they exist (the SDK handles them automatically):
130+
- 📄 `packages.config` - Use `PackageReference` instead
131+
- 📄 `Properties/AssemblyInfo.cs` - SDK generates this automatically
132+
- 📄 `app.config` - Usually not needed
133+
134+
#### Step 5: Update Package References
135+
136+
Convert from `packages.config` to `PackageReference` format in your `.csproj`:
137+
138+
```xml
139+
<ItemGroup>
140+
<PackageReference Include="Microsoft.VisualStudio.SDK" Version="17.*" />
141+
<PackageReference Include="Microsoft.VSSDK.BuildTools" Version="17.*" PrivateAssets="all" />
142+
<!-- Add other packages your extension uses -->
143+
</ItemGroup>
144+
```
145+
146+
#### Step 6: Handle VSCT Files
147+
148+
If you have `.vsct` files, they're automatically included. Remove any explicit `<VSCTCompile>` items unless you need custom metadata.
149+
150+
#### Step 7: Build and Test
151+
152+
```bash
153+
dotnet build
154+
```
155+
156+
Fix any errors that arise. Common issues:
157+
- ❌ **Missing types**: Add the appropriate `PackageReference`
158+
- ❌ **Duplicate files**: Remove explicit includes that conflict with auto-inclusion
159+
- ❌ **Resource files**: Ensure `VSPackage.resx` files are in the project
160+
161+
#### ✅ Migration Checklist
162+
163+
- [ ] Replaced `.csproj` with SDK-style format
164+
- [ ] Added `<ProductArchitecture>amd64</ProductArchitecture>` to manifest
165+
- [ ] Converted `packages.config` to `PackageReference`
166+
- [ ] Removed `Properties/AssemblyInfo.cs`
167+
- [ ] Removed explicit file includes (now auto-included)
168+
- [ ] Updated version range to `[17.0, 19.0)` for VS 2022+
169+
- [ ] Build succeeds with `dotnet build`
170+
- [ ] F5 debugging works in Visual Studio
171+
172+
### 🛠️ Manual Setup
61173

62174
If you prefer to set up manually, create a `.csproj` file:
63175

@@ -104,9 +216,9 @@ Then create `source.extension.vsixmanifest`:
104216
</PackageManifest>
105217
```
106218

107-
## Features
219+
## ✨ Features
108220

109-
### Source Generators
221+
### 🔮 Source Generators
110222

111223
The SDK includes source generators that create compile-time constants from your manifest files.
112224

@@ -159,11 +271,11 @@ public static class MyCommandsVsct
159271
}
160272
```
161273

162-
#### Generated Files Location
274+
#### 📁 Generated Files Location
163275

164276
Generated source files are written to the `Generated/` folder in your project and are visible in Solution Explorer. They're marked as auto-generated so you know not to edit them directly.
165277

166-
### Version Override
278+
### 🏷️ Version Override
167279

168280
Update the VSIX version at build time without manually editing the manifest:
169281

@@ -173,33 +285,33 @@ dotnet build -p:SetVsixVersion=2.0.0
173285

174286
This updates the `source.extension.vsixmanifest` file with the new version, rebuilds with the correct version in all outputs (including the generated `VsixInfo.Version` constant), and produces the VSIX with the specified version.
175287

176-
This is useful for CI/CD pipelines:
288+
Perfect for CI/CD pipelines:
177289

178290
```yaml
179291
# GitHub Actions example
180292
- name: Build Release
181293
run: dotnet build -c Release -p:SetVsixVersion=${{ github.ref_name }}
182294
```
183295
184-
### Auto-Inclusion
296+
### 📂 Auto-Inclusion
185297
186298
The SDK automatically includes common VSIX files:
187299
188-
- `*.vsct` files as `VSCTCompile` items
189-
- `VSPackage.resx` files with proper metadata
190-
- `source.extension.vsixmanifest` as an `AdditionalFile` for source generators
300+
- 📄 `*.vsct` files as `VSCTCompile` items
301+
- 📄 `VSPackage.resx` files with proper metadata
302+
- 📄 `source.extension.vsixmanifest` as an `AdditionalFile` for source generators
191303

192-
### F5 Debugging
304+
### 🐛 F5 Debugging
193305

194306
Press F5 to launch the Visual Studio Experimental Instance with your extension loaded. This works automatically when:
195307
- Building in Debug configuration
196308
- Building inside Visual Studio (not `dotnet build`)
197309

198-
### Smart Deployment
310+
### 🚀 Smart Deployment
199311

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

202-
### Publish Manifest Generation
314+
### 📋 Publish Manifest Generation
203315

204316
The SDK automatically generates a `publish.manifest.json` file for publishing to the VS Marketplace. All values are extracted from your VSIX manifest:
205317

@@ -236,7 +348,7 @@ To disable publish manifest generation:
236348
</PropertyGroup>
237349
```
238350

239-
## Configuration
351+
## ⚙️ Configuration
240352

241353
### Properties
242354

@@ -282,122 +394,12 @@ Or disable specific categories:
282394
</PropertyGroup>
283395
```
284396

285-
## Migrating from Legacy Projects
286-
287-
If you have an existing non-SDK style VSIX project, follow these steps to convert it.
288-
289-
### Step 1: Back Up Your Project
290-
291-
Before making changes, ensure your project is committed to source control or backed up.
292-
293-
### Step 2: Replace the .csproj Content
294-
295-
Replace your entire `.csproj` file with the SDK-style format:
296-
297-
**Before (Legacy):**
298-
```xml
299-
<?xml version="1.0" encoding="utf-8"?>
300-
<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
301-
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('...')" />
302-
<PropertyGroup>
303-
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
304-
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
305-
<ProjectGuid>{YOUR-GUID}</ProjectGuid>
306-
<OutputType>Library</OutputType>
307-
<AppDesignerFolder>Properties</AppDesignerFolder>
308-
<RootNamespace>MyExtension</RootNamespace>
309-
<AssemblyName>MyExtension</AssemblyName>
310-
<TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>
311-
<!-- ... many more lines ... -->
312-
</PropertyGroup>
313-
<!-- ... hundreds of lines of XML ... -->
314-
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
315-
<Import Project="$(VSToolsPath)\VSSDK\Microsoft.VsSDK.targets" Condition="'$(VSToolsPath)' != ''" />
316-
</Project>
317-
```
318-
319-
**After (SDK-style):**
320-
```xml
321-
<Project Sdk="CodingWithCalvin.VsixSdk/1.0.0">
322-
323-
<PropertyGroup>
324-
<TargetFramework>net472</TargetFramework>
325-
<RootNamespace>MyExtension</RootNamespace>
326-
<AssemblyName>MyExtension</AssemblyName>
327-
</PropertyGroup>
328-
329-
<ItemGroup>
330-
<PackageReference Include="Microsoft.VisualStudio.SDK" Version="17.*" />
331-
<PackageReference Include="Microsoft.VSSDK.BuildTools" Version="17.*" PrivateAssets="all" />
332-
</ItemGroup>
333-
334-
</Project>
335-
```
336-
337-
### Step 3: Update the VSIX Manifest for VS 2022+
338-
339-
Add `<ProductArchitecture>amd64</ProductArchitecture>` to each `InstallationTarget`:
340-
341-
```xml
342-
<Installation>
343-
<InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0, 19.0)">
344-
<ProductArchitecture>amd64</ProductArchitecture>
345-
</InstallationTarget>
346-
<!-- Repeat for Professional, Enterprise if needed -->
347-
</Installation>
348-
```
349-
350-
### Step 4: Remove Unnecessary Files
351-
352-
Delete these files if they exist (the SDK handles them automatically):
353-
- `packages.config` - Use `PackageReference` instead
354-
- `Properties/AssemblyInfo.cs` - SDK generates this automatically
355-
- `app.config` - Usually not needed
356-
357-
### Step 5: Update Package References
358-
359-
Convert from `packages.config` to `PackageReference` format in your `.csproj`:
360-
361-
```xml
362-
<ItemGroup>
363-
<PackageReference Include="Microsoft.VisualStudio.SDK" Version="17.*" />
364-
<PackageReference Include="Microsoft.VSSDK.BuildTools" Version="17.*" PrivateAssets="all" />
365-
<!-- Add other packages your extension uses -->
366-
</ItemGroup>
367-
```
368-
369-
### Step 6: Handle VSCT Files
370-
371-
If you have `.vsct` files, they're automatically included. Remove any explicit `<VSCTCompile>` items unless you need custom metadata.
372-
373-
### Step 7: Build and Test
374-
375-
```bash
376-
dotnet build
377-
```
378-
379-
Fix any errors that arise. Common issues:
380-
- **Missing types**: Add the appropriate `PackageReference`
381-
- **Duplicate files**: Remove explicit includes that conflict with auto-inclusion
382-
- **Resource files**: Ensure `VSPackage.resx` files are in the project
383-
384-
### Migration Checklist
385-
386-
- [ ] Replaced `.csproj` with SDK-style format
387-
- [ ] Added `<ProductArchitecture>amd64</ProductArchitecture>` to manifest
388-
- [ ] Converted `packages.config` to `PackageReference`
389-
- [ ] Removed `Properties/AssemblyInfo.cs`
390-
- [ ] Removed explicit file includes (now auto-included)
391-
- [ ] Updated version range to `[17.0, 19.0)` for VS 2022+
392-
- [ ] Build succeeds with `dotnet build`
393-
- [ ] F5 debugging works in Visual Studio
394-
395-
## Requirements
397+
## 📋 Requirements
396398

397399
- Visual Studio 2022 or later
398400
- .NET Framework 4.7.2+ target framework
399401

400-
## Building from Source
402+
## 🏗️ Building from Source
401403

402404
```bash
403405
# Clone the repository
@@ -413,12 +415,12 @@ dotnet pack src/CodingWithCalvin.VsixSdk.Templates/CodingWithCalvin.VsixSdk.Temp
413415
# Packages output to artifacts/packages/
414416
```
415417

416-
## Contributors
418+
## 👥 Contributors
417419

418420
<!-- readme: contributors -start -->
419421
<!-- readme: contributors -end -->
420422

421-
## License
423+
## 📄 License
422424

423425
MIT License - see [LICENSE](LICENSE) for details.
424426

0 commit comments

Comments
 (0)