diff --git a/.github/agents/docseditor.agent.md b/.github/agents/docseditor.agent.md index 43ca3d27e5116..f5a7208eb15fb 100644 --- a/.github/agents/docseditor.agent.md +++ b/.github/agents/docseditor.agent.md @@ -124,6 +124,15 @@ When editing, focus on these areas in order of priority: - ❌ Remove filler words: "quite", "very", "easily", "simply" (unless essential) - Look for ANY unnecessary prepositional phrases or filler words +**SCAN FOR AND REPLACE ambiguous "this" references (these are examples - find ALL similar patterns):** +- "This" at the start of a sentence or clause is often ambiguous — replace it with the specific noun it refers to +- ❌ "This creates a file" → ✅ "The command creates a file" +- ❌ "This is useful when..." → ✅ "The feature is useful when..." +- ❌ "This can be configured by..." → ✅ "The setting can be configured by..." +- ❌ "Configure this before deploying" → ✅ "Configure the connection string before deploying" +- Look for ANY sentence or clause where "this" starts or is the subject, and replace it with the explicit noun +- **NOTE:** "this" is acceptable when used as an adjective directly before a noun ("this method", "this file"), but avoid it when used alone as a pronoun + **SCAN FOR AND ENSURE consistent terminology (apply this principle throughout):** - Pick one term for each concept and use it throughout - ❌ "Because" and "Since" mixed → ✅ "Because" consistently @@ -219,6 +228,7 @@ After editing, you MUST verify: - [ ] ALL contractions added where appropriate - [ ] ALL verbose phrases simplified - [ ] ALL weak constructions eliminated +- [ ] ALL ambiguous "this" pronoun uses replaced with explicit nouns - [ ] Content maintains technical accuracy - [ ] Tone is conversational and helpful - [ ] Sentences are concise and scannable diff --git a/.github/instructions/Markdown.WritingStyle.instructions.md b/.github/instructions/Markdown.WritingStyle.instructions.md index 045c291e0e7fa..39e71b578e3ca 100644 --- a/.github/instructions/Markdown.WritingStyle.instructions.md +++ b/.github/instructions/Markdown.WritingStyle.instructions.md @@ -21,6 +21,7 @@ NEVER use: - "we" or "our" when referring to documentation authors or product teams - Jargon or overly complex technical language - Weak phrases like "you can" or "there is/are/were" unless they add value +- "this" as a standalone pronoun — replace it with the specific noun it refers to (adjectival use before a noun, such as "this method", is fine) ALWAYS: - Write like you speak using everyday words diff --git a/.github/instructions/Snippets.Migrate.instructions.md b/.github/instructions/Snippets.Migrate.instructions.md deleted file mode 100644 index a5efb8732895b..0000000000000 --- a/.github/instructions/Snippets.Migrate.instructions.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -description: Migrate code from the old ~/samples/snippets/ location to the relative ./snippets location. ---- - -# Migrate code snippets - -**IMPORTANT**: Unless otherwise asked to, **only** edit the article file in context. At the end of your operations you may ask for permission to edit other articles referencing the same snippets. - -## Repository structure for code snippets - -**IMPORTANT**: This repository has TWO different locations for code snippets: - -### Old location (legacy - to be migrated FROM) -- Path: `~/samples/snippets/` -- Example: `~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.Clipboard/CS/form1.cs` -- Status: Legacy, should be migrated to new location - -### New location (current standard - migrate TO) -- Path pattern: `./snippets/{doc-file}/{code-language}/` -- Example: `./snippets/how-to-add-data-to-the-clipboard/csharp/form1.cs` - -**Path components explained:** -- `{doc-file}`: The markdown article filename WITHOUT the `.md` extension - - Example: For article `how-to-add-data-to-the-clipboard.md` → use `how-to-add-data-to-the-clipboard` -- `{code-language}`: - - `csharp`: For C# code - - `vb`: For Visual Basic code - -## Legacy code characteristics (migrate FROM these) - -**Location**: `~/samples/snippets/` folder -**Problems with legacy code:** -- Usually for .NET Framework (outdated) -- Often incomplete or non-compilable -- May lack project files -- Uses outdated syntax and patterns - -**Legacy article references look like this:** -```markdown -[!code-{code-language}[description](~/samples/snippets/{path-to-file}#{snippet-identifier})] -``` -It's possible that the reference was already migrated, but the code wasn't, which looks like this: -```markdown -:::code language="{code-language}" source="~/samples/snippets/{path-to-file}" id="{snippet-identifier}"::: -``` -Based on the {path-to-file} you can determine if it's in the old system or not. - -## Current code requirements (migrate TO these) - -**Location**: `./snippets/{doc-file}/{code-language}/` - -**Requirements for current code standards:** -- ✅ MUST be complete and compilable -- ✅ MUST include a project file -- ✅ MUST target appropriate .NET version (see targeting rules below) -- ✅ MUST provide BOTH C# and Visual Basic versions -- ✅ MUST use appropriate syntax for the target framework -- ✅ MUST use meaningful, descriptive snippet identifiers in CamelCase format - - **Examples** of good snippet identifiers: `BasicClipboardData`, `CustomDataFormat`, `ClipboardImageHandling` - - **Avoid** simplistic identifiers like `1`, `2`, `code1`, or `snippet1` - -**Current article references look like this:** -```markdown -:::code language="{code-language}" source="{file-path}" id="{snippet-identifier}"::: -``` - -**Framework targeting rules:** -- **Migration vs. Modernization**: - - **Migration**: Move code to new location with minimal changes - - **Modernization**: Update code to use latest .NET features and best practices -- **When to modernize**: Unless told not to modernize, always modernize from .NET Framework to the latest .NET - -## Migration steps (follow in order) - -**WHEN TO MIGRATE**: Migrate code when you encounter articles with references to `~/samples/snippets/` paths. - -**STEP-BY-STEP PROCESS:** - -### 1. Analyze existing code and article context -- **Find**: Locate the legacy snippet file in `~/samples/snippets/` -- **Identify**: Determine the programming language (C# or Visual Basic) -- **Extract**: Note the snippet identifier used in the article reference - -### 2. Create new folder structure -- **Pattern**: `./snippets/{doc-file}/{code-language}/` -- **Example**: For article `clipboard-operations.md` → create `./snippets/clipboard-operations/csharp/` - -### 3. Migrate and update code -- **Copy**: Copy only the snippet code (and any supporting code to compile the snippet) to the new location -- **Complete**: Ensure code is fully functional and compilable -- **Project file**: Create or update project file with appropriate target framework - -### 4. Create both language versions -- **Requirement**: MUST provide both C# and Visual Basic versions -- **C# path**: `./snippets/{doc-file}/csharp/` -- **VB path**: `./snippets/{doc-file}/vb/` - -### 5. Update article references -- **Replace**: Change from legacy `[!code-...]` format to modern `:::code...:::` format -- **Before**: `[!code-csharp[description](~/samples/snippets/path/file.cs#snippet1)]` -- **After**: `:::code language="csharp" source="./snippets/doc-name/csharp/file.cs" id="BasicClipboardData":::` -- **Note**: Use meaningful CamelCase identifiers instead of simple numbers - -### 6. Validate -- **Build**: Ensure all code compiles successfully -- **Test**: Verify snippet references work in the article - -### 7. Delete -- **Identify**: - - Check if the old snippet file is used by any other articles - - Some articles may use a relative path to the `samples` folder, so simply search for links to `samples/snippets/...` - - Be confident that all legacy snippets use a `samples/snippets` folder structure -- **Delete**: If old snippet is no longer used by any article, delete it. - -## Common mistakes to avoid - -- ❌ **Don't** assume all code needs to be modernized - check article context first -- ❌ **Don't** modernize .NET Framework-specific articles unless specifically requested -- ❌ **Don't** forget to create both C# and VB versions -- ❌ **Don't** forget to update ALL article references to the migrated code -- ❌ **Don't** leave incomplete or non-compilable code diff --git a/.github/instructions/Snippets.Push.instructions.md b/.github/instructions/Snippets.Push.instructions.md deleted file mode 100644 index c9fef42c545a0..0000000000000 --- a/.github/instructions/Snippets.Push.instructions.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -description: Push inline code block snippets out of articles into standalone files with proper project structure. ---- - -# Push inline code snippets to files - -**IMPORTANT**: Unless otherwise asked to, **only** edit the article file in context. At the end of your operations you may ask for permission to edit other articles that might benefit from the same snippet extraction. - -**IMPORTANT**: Don't share code across multiple articles. Each article should have its own copy of the snippet in its own folder structure. - -## Quick Reference - -**WHEN TO PUSH:** Code >6 lines, complete/compilable examples, or when specifically requested -**FOLDER PATTERN:** `./snippets/{doc-file}/{csharp|vb}/` -**PROJECT CREATION:** Always use the `dotnet new console` command to create a new project for the code language -**LANGUAGES:** Create both C# and Visual Basic versions (if applicable). -**SNIPPET IDs:** Use CamelCase region markers like `` -**ARTICLE REFS:** Replace with `:::code language="csharp" source="./path" id="SnippetId":::` - -## When to push snippets out of articles - -**PUSH SNIPPETS WHEN:** -- Code blocks are longer than 6 lines or the rest of the article is using them -- Code demonstrates complete, compilable examples -- Code represents a complete application or significant functionality -- User specifically requests snippet extraction - -**KEEP INLINE WHEN:** -- Code blocks are 6 lines or shorter (unless you find an example in the article's snippets folder) -- Code shows configuration snippets (XAML, JSON, XML) (unless you find an example in the article's snippets folder) -- Code demonstrates simple one-liner examples (unless you find an example in the article's snippets folder) -- Code is pseudo-code or conceptual examples - -## Target folder structure - -**IMPORTANT**: Follow a folder structure based on the article and code language: - -### New snippet location (standard) -- Path pattern: `./snippets/{doc-file}/{code-language}/` -- Example: `./snippets/create-windows-forms-app/csharp/` - -**Path components explained:** -- `{doc-file}`: The markdown article filename WITHOUT the `.md` extension - - Example: For article `create-windows-forms-app.md` → use `create-windows-forms-app` -- `{code-language}`: - - `csharp`: For C# code - - `vb`: For Visual Basic code - -## Push process - -### 1. Analyze and prepare -- Locate code to migrate -- Create folder structure: `./snippets/{doc-file}/{csharp|vb}/` - -### 2. Create projects and extract code -- Run appropriate `dotnet new` command in each language folder, **don't** specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible -- Copy and complete code to make it compilable -- Add missing using statements, namespaces, class declarations -- Modernize code patterns if targeting current .NET -- Test compilation with `dotnet build` - -### 3. Add snippet references and update article -- Add CamelCase region markers: `// ` and `// ` -- Use same identifiers across C# and VB versions -- Replace inline code with snippet references: - ```markdown - :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick"::: - :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="ButtonClick"::: - ``` -- DO NOT use language tabs, simply put them side-by-side -- Verify all paths and references are correct - -### 4. Make sure frontmatter specifies a language when required - -If both CSharp and VB examples are provided make sure the following frontmatter is at the top of the article: - -```yml -dev_langs: - - "csharp" - - "vb" -``` - -## Common mistakes to avoid - -- ❌ Extracting short snippets (≤6 lines) without request -- ❌ Skipping `dotnet new` commands or creating incomplete projects -- ❌ Missing C# or VB versions -- ❌ Using language tabs -- ❌ Wrong project type (winforms vs wpf vs console) -- ❌ Incorrect framework targeting (net vs framework) -- ❌ Missing or inconsistent snippet region identifiers -- ❌ Code that doesn't compile - -## Quality checklist - -- ✅ Correct folder structure and project type -- ✅ Both C# and VB versions compile successfully -- ✅ Snippet regions use CamelCase identifiers -- ✅ Article uses correct `:::code...:::` syntax with valid paths \ No newline at end of file diff --git a/.github/prompts/Snippets.Migrate.prompt.md b/.github/prompts/Snippets.Migrate.prompt.md new file mode 100644 index 0000000000000..8d43796bcc0f7 --- /dev/null +++ b/.github/prompts/Snippets.Migrate.prompt.md @@ -0,0 +1,112 @@ +--- +agent: agent +model: Claude Sonnet 4.6 (copilot) +description: Migrate code from the old ~/samples/snippets/ location to the relative ./snippets location. +--- + +# Migrate code snippets + +We no longer use the `~/samples/snippets/` location for code snippets. All code snippets must be migrated to the new `./snippets/` location, which is relative to the article using the snippet. Generally, snippets in the old location are outdated, incomplete, and often can't compile. The new location requires that all snippets be complete, compilable, and include project files. Additionally, the new location requires both C# and Visual Basic versions of each snippet. + +**IMPORTANT**: Unless otherwise asked to, **only** edit the article file in context. At the end of your operations you may ask for permission to edit other articles referencing the same snippets. + +## Repository structure for code snippets + +**IMPORTANT**: This repository has TWO different locations for code snippets: + +### Old location (legacy - to be migrated FROM) +- Path: `~/samples/snippets/` +- Example: `~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.Clipboard/CS/form1.cs` + +**Problems with legacy code:** +- Written for .NET Framework (outdated) +- Often incomplete and can't compile +- May lack project files +- Uses outdated syntax and patterns + +**Legacy article references generally use old syntax:** +```markdown +[!code-{code-language}[description](~/samples/snippets/{path-to-file}#{snippet-identifier})] +``` +### New location (current standard - migrate TO) +- Path pattern: `./snippets/{article-filename-using-snippet}/[optional-sub-subject]/{code-language}/` +- Example C#: `./snippets/anchors-in-regular-expressions/csharp/Form1.cs` +- Example VB: `./snippets/anchors-in-regular-expressions/vb/Form1.vb` + +**Path components explained:** +- `./`: Current folder of the article being edited +- `snippets/`: Root folder for all snippets +- `{article-filename-using-snippet}`: The markdown article filename WITHOUT the `.md` extension + - Example: For article `anchors-in-regular-expressions.md` → use `anchors-in-regular-expressions` +- `[optional-sub-subject]`: An optional subfolder to avoid clashes. Used when a snippet in the article can't be merged with existing snippets. Examples of this would be two different snippets that both use a `Program.cs` file. For example, if there were two snippets in the same file demonstrating an Async `main` and a non-Async `main`, you could create descriptive subfolders like `AsyncProgram/` and `SyncProgram/` to avoid conflicts. +- `{code-language}`: + - `csharp`: For C# code + - `vb`: For Visual Basic code + +**IMPORTANT**: Exception to the rules about having multiple code languages: For language guide articles, only the guide's language is required — do not create a version in the other language. The C# Language guide only contains CS code snippets, and the VB Language guide only contains VB code snippets. All other articles should follow the full path pattern including the `{code-language}/` subfolder. For example, you wouldn't use the `./snippets/article-name/csharp/` or `./snippets/article-name/vb/` folder structures for an article in the C# language guide, the folder would simply be `./snippets/article-name/` and the code in C#. The same applies to the VB language guide. + +**Requirements for current code standards:** +- ✅ MUST be complete and compilable +- ✅ MUST include a project file +- ✅ MUST target the latest .NET version +- ✅ MUST provide BOTH C# and Visual Basic versions +- ✅ MUST use appropriate syntax for the target framework +- ✅ MUST use meaningful, descriptive snippet identifiers in CamelCase format + - **Examples** of good snippet identifiers: `BasicClipboardData`, `CustomDataFormat`, `ClipboardImageHandling` + - **Avoid** simplistic identifiers like `1`, `2`, `code1`, or `snippet1` + +**Current article references look like this:** +```markdown +:::code language="{code-language}" source="{relative-file-path}" id="{snippet-identifier}"::: +``` + +## Migration steps (follow in order) + +**STEP-BY-STEP PROCESS:** + +### 1. Analyze existing code and article context +- **Find**: Locate the legacy snippet file references to `~/samples/snippets/` (path may be relative, navigating back to the root `samples` folder) +- **Identify**: Determine the programming language (C# or Visual Basic) +- **Extract**: Note the snippet identifier used in the article reference + +### 2. Create new or reuse existing folder structure +- **Pattern**: `./snippets/{article-filename-using-snippet}/[optional-sub-subject]/{code-language}/` +- **Example**: For article `clipboard-operations.md` → create `./snippets/clipboard-operations/csharp/` +- **Reuse**: If the article already has snippets in the new location, reuse the existing folder structure and try to merge the code into the existing snippets if possible. Use new classes and code files as needed. Code **ONLY** needs to compile, it doesn't have to run from the program main. +- **Create**: If no existing folder structure exists for the article, create a new one following the pattern above. +- **New projects**: **NEVER** create project files manually. Always use the `dotnet` CLI to ensure correct formatting and structure of new code. Projects should be console apps unless otherwise required (such as a Windows Forms-related snippet) + +### 3. Migrate and update code +- **Copy**: Copy only the snippet code (and any supporting code to compile the snippet) to the new location +- **Complete**: Ensure code is fully functional and compilable + +### 4. Create both language versions +- **Requirement**: MUST provide both C# and Visual Basic versions, except for language guide articles (C# or VB guide), where only the guide's language is required. +- **Standard articles** (both languages required): + - **C# path**: `./snippets/{article-filename-using-snippet}/csharp/` + - **VB path**: `./snippets/{article-filename-using-snippet}/vb/` +- **Language guide articles** (single language, no `{code-language}` subfolder): + - **C# guide path**: `./snippets/{article-filename-using-snippet}/` + - **VB guide path**: `./snippets/{article-filename-using-snippet}/` + +### 5. Update article references +- **Replace**: Change from legacy `[!code-...]` format to modern `:::code...:::` format +- **Before**: `[!code-csharp[description](~/samples/snippets/path/file.cs#snippet1)]` +- **After**: `:::code language="csharp" source="./snippets/article-name/csharp/file.cs" id="BasicClipboardData":::` +- **Note**: Use meaningful CamelCase identifiers instead of simple numbers + +### 6. Validate +- **Build**: Ensure all code compiles successfully + +### 7. Delete +- **Identify**: + - Check if the old snippet file is used by any other articles. Search for the old snippet path across the repository to find any references. This can be done by searching for links to `samples/snippets/...` (the file path used in the snippet reference) since some articles may use a relative path to the `samples` folder instead of absolute paths. +- **Delete**: If old snippet was migrated and is no longer used by any other article, delete it. + +## Common mistakes to avoid + +- ❌ **Don't** assume all code needs to be modernized - check article context first +- ❌ **Don't** forget to create both C# and VB versions +- ❌ **Don't** mix up the framework targeting (net vs framework) +- ❌ **Don't** forget to update ALL article references to the migrated code +- ❌ **Don't** leave incomplete or non-compilable code diff --git a/.github/prompts/Snippets.Push.prompt.md b/.github/prompts/Snippets.Push.prompt.md new file mode 100644 index 0000000000000..7c45546f99ad9 --- /dev/null +++ b/.github/prompts/Snippets.Push.prompt.md @@ -0,0 +1,115 @@ +--- +agent: agent +model: Claude Sonnet 4.6 (copilot) +description: Push inline code block snippets out of articles into standalone files with proper project structure. +--- + +# Push inline code snippets to files + +**IMPORTANT**: Unless otherwise asked to, **only** extract snippets from the article file in context. At the end of your operations you may ask for permission to edit other articles that might benefit from the same snippet extraction. + +**IMPORTANT**: Don't share code across multiple articles. Each article should have its own copy of the snippet in its own folder structure. + +**IMPORTANT**: If only XAML snippets are present, only create C# projects to hold the XAML. Do not create VB projects for XAML-only snippets. + +## When to push snippets out of articles + +**PUSH SNIPPETS WHEN:** +- Code blocks are longer than 6 lines +- Code demonstrates complete, compilable examples +- Code represents a complete application or significant functionality +- User specifically requests snippet extraction + +**KEEP INLINE WHEN:** +- Code blocks are 6 lines or shorter +- Code is pseudo-code or conceptual examples + +## Target folder structure +- Path pattern: `./snippets/{article-name}/[optional-sub-subject]/{code-language}/` +- Example C#: `./snippets/create-app/csharp/` +- Example VB: `./snippets/create-app/vb/` + +**Path components explained:** +- `./`: Current folder of the article being edited +- `snippets/`: Root folder for all snippets +- `{article-name}`: The markdown article filename WITHOUT the `.md` extension + - Example: For article `create-app.md` → use `create-app` +- `[optional-sub-subject]`: An optional subfolder to avoid clashes. Used when snippets in the same article can't be merged — for example, two snippets that both require a `Program.cs` file but demonstrate different things. Use descriptive subfolder names like `AsyncProgram/` and `SyncProgram/`. +- `{code-language}`: + - `csharp`: For C# code (also use for XAML snippets) + - `vb`: For Visual Basic code + +**Language guide exception**: For articles in the C# or VB language guides, only the guide's language is required — do not create a version in the other language, and omit the `{code-language}/` subfolder: +- C# guide path: `./snippets/{article-name}/` +- VB guide path: `./snippets/{article-name}/` + +## Push process + +### 1. Analyze and prepare +- Locate code blocks >6 lines or complete examples (unless overridden by user request) +- Identify the programming language(s) used +- Determine if the article is in a language guide (C# or VB) to apply the language exception + +### 2. Decide how code will be placed +- If the article talks about single-file apps, **STOP** and ask the user if they want to use a single-file app or a traditional project-based app +- If the article doesn't talk about single-file apps, assume the code samples must be put into a project-based app + +### 2.1 Project-based apps +- This is the default for moving code snippets from an article +- **NEVER** create project files manually. +- **ALWAYS** use the `dotnet` CLI. Default to console apps (`dotnet new console`) unless the snippet requires a different project type (for example, `dotnet new winforms` for a Windows Forms snippet). Don't specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible. + +### 2.2 Single-file apps +- This is not the default. You must have a good reason to use this mode, such as the user requested it or the article itself references single-file apps along with the snippets +- Only C# is supported +- VB snippets must use a project-based app approach +- Multiple single-file apps can share the same folder for the article +- Instead of `Program.cs`, they can be named anything +- They are compiled with `dotnet run file.cs` +- Folder must not have a project file + +### 3. Extract code +- Copy and complete code to make it compilable. Code only needs to compile — it doesn't have to run from `Main`. +- Add missing using statements, namespaces, and class declarations as needed. +- Build to verify compilation with `dotnet build`. + +### 4. Add snippet markers and update article references +- Add CamelCase region markers around each snippet. Snippet markers are added as comments in the language of the code file: + - C#: `// ` and `// ` + - VB: `' ` and `' ` +- The angle brackets (`<` and `>`) are part of the comment markers only. The snippet identifier itself is the bare CamelCase name (for example, `SnippetId`), which is what you use in the `id` attribute. +- Use the same identifiers across C# and VB versions. +- Use meaningful, descriptive identifiers — avoid `1`, `2`, `code1`, or `snippet1`. +- Replace each inline code block with a `:::code:::` reference: + ```markdown + :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick"::: + :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="ButtonClick"::: + ``` +- DO NOT use language tabs in the article — place references side-by-side, like so: + ```markdown + :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick"::: + + :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="ButtonClick"::: + ``` +- Verify all paths and identifiers are correct. + +### 5. Update article frontmatter +If both C# and VB examples are provided, ensure the following frontmatter is present at the top of the article: + +```yml +dev_langs: + - "csharp" + - "vb" +``` + +If a single language is used (like in the language guides), omit the `dev_langs` section. + +## Common mistakes to avoid + +- ❌ Extracting short snippets (≤6 lines) without being asked +- ❌ Creating project files manually instead of using `dotnet new` (when using project-based apps) +- ❌ Missing C# or VB versions for standard articles +- ❌ Creating VB projects for XAML-only snippets +- ❌ Using language tabs instead of side-by-side references +- ❌ Missing or inconsistent snippet region identifiers +- ❌ Code that doesn't compile diff --git a/.github/prompts/Snippets.Upgrade.prompt.md b/.github/prompts/Snippets.Upgrade.prompt.md new file mode 100644 index 0000000000000..c75faddda4672 --- /dev/null +++ b/.github/prompts/Snippets.Upgrade.prompt.md @@ -0,0 +1,104 @@ +--- +agent: agent +model: Claude Sonnet 4.6 (copilot) +description: Upgrade snippets to the latest .NET and possibly migrate from .NET Framework +--- + +# Code Snippet Upgrade Instructions + +## When to Apply These Instructions + +Apply these instructions when working with code snippets that need modernization, especially when: +- Improving snippet quality and completeness +- Upgrading .NET Framework code to modern .NET +- Adding missing language versions (C# or VB) + +## Snippet Structure Requirements + +All snippets must follow this folder structure relative to the referencing article: + +``` +./snippets/{article-name}/[optional-sub-subject]/{code-language}/ +``` + +**Path components explained:** +- `./`: Current folder of the article being edited +- `snippets/`: Root folder for all snippets +- `{article-name}`: The markdown article filename WITHOUT the `.md` extension +- `[optional-sub-subject]`: An optional subfolder to avoid clashes — use when two snippets in the same article can't be merged (for example, both require a `Program.cs` file). Use descriptive names like `AsyncProgram/` and `SyncProgram/`. +- `{code-language}`: `csharp` for C#, `vb` for Visual Basic + +**Examples:** +- `./snippets/how-to-add-data-to-the-clipboard/csharp/MainForm.cs` +- `./snippets/how-to-add-data-to-the-clipboard/vb/MainForm.vb` + +**Language guide exception**: For articles in the C# or VB language guides, only the guide's language is required — do not create a version in the other language, and omit the `{code-language}/` subfolder. The path is simply `./snippets/{article-name}/`. + +## Required Upgrade Actions + +### 1. File Naming and Organization +- Use PascalCase for class names and file names (e.g., `MainForm.cs`, `DataProcessor.cs`) +- Organize files logically within the language folder + +### 2. Snippet Identifiers and Naming +- Use meaningful, descriptive snippet identifiers in CamelCase format +- Replace simplistic identifiers (like single numbers) with descriptive names +- Good examples: `BasicClipboardData`, `CustomDataFormat`, `ClipboardImageHandling` +- Avoid: `1`, `2`, `code1`, `snippet1` +- Identifiers should clearly describe the code's purpose or functionality + +### 3. Syntax Modernization +- Target the latest stable .NET version +- Use modern C# features: + - File-scoped namespaces + - Top-level statements where appropriate + - Pattern matching + - String interpolation + - `var` where type is obvious + - Modern `using` statements + +### 4. Project File Requirements +- **NEVER** create project files manually. Always use the `dotnet` CLI. Default to console apps (`dotnet new console`) unless the snippet requires a different project type. Don't specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible. +- Ensure a complete, compilable project structure with an appropriate `.csproj` or `.vbproj` file +- Code only needs to compile — it doesn't have to run from `Main` +- Verify compilation with `dotnet build` + +### 5. Code Quality Standards +- Ensure code compiles without errors +- Follow .NET naming conventions +- Use appropriate access modifiers +- Include necessary `using`/`import` statements + +### 6. Language Parity +- Create both C# and VB.NET versions for standard articles +- For language guide articles (C# or VB guide), only the guide's language is required +- Maintain functional equivalence between language versions +- Adapt language-specific idioms appropriately + +## Example Transformation + +**Before (outdated structure):** +``` +~/samples/snippets/csharp/clipboard/code.cs +``` + +**After (current structure):** +``` +./snippets/how-to-add-data-to-the-clipboard/csharp/ +├── ClipboardExample.csproj +├── MainForm.cs +└── Program.cs + +./snippets/how-to-add-data-to-the-clipboard/vb/ +├── ClipboardExample.vbproj +├── MainForm.vb +└── Program.vb +``` + +## Common mistakes to avoid + +- ❌ Using the old `[net|framework]` subfolder in paths +- ❌ Creating project files manually instead of using `dotnet new` +- ❌ Missing C# or VB versions for standard articles +- ❌ Using simplistic or non-descriptive snippet identifiers +- ❌ Code that doesn't compile \ No newline at end of file