diff --git a/.github/prompts/ErrorConsolidation.1.Setup.prompt.md b/.github/prompts/ErrorConsolidation.1.Setup.prompt.md new file mode 100644 index 0000000000000..704073230b43b --- /dev/null +++ b/.github/prompts/ErrorConsolidation.1.Setup.prompt.md @@ -0,0 +1,98 @@ +--- +model: Claude Opus 4.6 (copilot) +agent: agent +description: Creates a new consolidated compiler error/warning article skeleton and TOC entry +tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'todo'] +--- + +# Create a consolidated error article + +You are creating a new consolidated compiler error/warning article. The user will provide: + +- **Destination filename** — the name of the new `.md` file (e.g., `overloaded-operator-errors.md`) +- **Theme description** — a short description of the theme (e.g., "overflow, underflow, and checked and unchecked operators") +- **Seed error codes** (optional) — a list of new, undocumented error codes to include from the start + +## Step 1: Ask for TOC placement + +Ask the user: *Where in the TOC should this entry be placed? Provide the name or href of the existing entry it should appear after.* + +Wait for the user's answer before proceeding. + +## Step 2: Create the destination file + +Create the file at `docs/csharp/language-reference/compiler-messages/{destination-filename}` with this structure: + +```yaml +--- +title: "Resolve errors and warnings related to {theme description}" +description: "This article helps you diagnose and correct compiler errors and warnings related to {theme description}" +f1_keywords: + # populated from seed error codes, sorted numerically +helpviewer_keywords: + # populated from seed error codes, sorted numerically +ms.date: {today's date in MM/DD/YYYY format} +ai-usage: ai-assisted +--- +``` + +Then add the body: + +```markdown +# Resolve errors and warnings for {short theme title} + +This article covers the following compiler errors and warnings: + + + +``` + +## Step 3: Add the TOC entry + +Add an entry in `docs/csharp/language-reference/toc.yml` at the location the user specified. The entry format is: + +```yaml + - name: {Short theme title} + href: ./compiler-messages/{destination-filename} + displayName: > + {theme keywords}, + {CS codes sorted numerically, comma-separated} +``` + +Look at neighboring entries in the TOC for style and indentation guidance. + +## Step 4: Populate seed error codes (if provided) + +If the user provided seed error codes, process them as a batch: + +For each error code: + +1. Extract the numeric portion (e.g., `CS0220` → `220`). +2. Find the constant with that number in the Roslyn source file `../roslyn/src/Compilers/CSharp/Portable/Errors/ErrorCodes.cs`. The constant name maps to the symbolic name. +3. Find the corresponding `` element in `../roslyn/src/Compilers/CSharp/Portable/CSharpResources.resx` whose `name` attribute matches the `ErrorCodes.cs` constant name exactly, including the `ERR_` or `WRN_` prefix. +4. Read the verbatim error message from the `` child element. + +Then update the destination file: + +- Add each code to `f1_keywords` and `helpviewer_keywords` in sorted numeric order. +- Add an entry to the error list in the article body. Use this format: + ``` + - [**CS{NNNN}**](#anchor-tbd): *{verbatim error message}* + ``` + Use `#anchor-tbd` as the anchor — these will be updated in the Consolidate phase. + **Handling format placeholders:** The Roslyn source message may contain interpolation markers like `'{0}'`, `'{1}'`, etc. Replace these with descriptive terms that keep the text as close to the verbatim message as possible for SEO, while still reading as a coherent sentence. Use generic terms like `'type'`, `'value'`, `'operator'`, `'member'`, or `'method'` based on the context of the error. For example, `Constant value '{0}' cannot be converted to a '{1}'` becomes `Constant value 'value' cannot be converted to a 'type'`. Look at the XML `` element following the `` (if present) for hints about what each placeholder represents. +- Add each code to the `displayName` in the TOC entry, in sorted numeric order. + +For each seed code, also remove it from the `f1_keywords` front matter in `docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md`. + +## Step 5: Present for review + +**Stop and present the created skeleton to the user.** Show: + +1. The full destination file content +2. The new TOC entry +3. A summary of any codes removed from the catch-all file + +Wait for user approval before ending. Do not proceed to merging or searching — those are separate prompt files. diff --git a/.github/prompts/ErrorConsolidation.2.MergeExisting.prompt.md b/.github/prompts/ErrorConsolidation.2.MergeExisting.prompt.md new file mode 100644 index 0000000000000..e4544466cc57f --- /dev/null +++ b/.github/prompts/ErrorConsolidation.2.MergeExisting.prompt.md @@ -0,0 +1,88 @@ +--- +model: Claude Opus 4.6 (copilot) +agent: agent +description: Merges existing standalone error articles into a consolidated article +tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'todo'] +--- + +# Merge existing error articles into a consolidated article + +You are merging existing standalone compiler error/warning articles into a consolidated destination file. The user will provide: + +- **Destination filename** — the consolidated `.md` file in `docs/csharp/language-reference/compiler-messages/` +- **Theme description** — the theme these errors relate to +- **Source files** — a list of existing error article files to merge (already approved by the user) + +## Key file locations + +- **Destination file**: `docs/csharp/language-reference/compiler-messages/{destination-filename}` +- **TOC file**: `docs/csharp/language-reference/toc.yml` +- **Redirection file**: `.openpublishing.redirection.csharp.json` +- **Redirect script**: `.github/skills/redirect-article/scripts/create-redirect-entry.ps1` + +## Batch process: for each source file + +Process the entire approved list. For each source file: + +### 1. Read and extract + +Read the source file and extract: +- The error code (from the filename or front matter, e.g., `CS0220`) +- The error message: extract the numeric portion of the error code, find the constant with that number in `../roslyn/src/Compilers/CSharp/Portable/Errors/ErrorCodes.cs`, then find the matching `` element in `../roslyn/src/Compilers/CSharp/Portable/CSharpResources.resx` and read the verbatim text from its `` child element. +- The article body content (everything after the front matter and H1) + +### 2. Update the destination file + +**Front matter:** +- Add the error code to `f1_keywords` in sorted numeric order. +- Add the error code to `helpviewer_keywords` in sorted numeric order. + +**Error list:** +- Add an entry to the error list at the top of the article, in sorted numeric order. Format: + ``` + - [**CS{NNNN}**](#anchor-tbd): *{verbatim compiler error message}* + ``` + Use `#anchor-tbd` as a placeholder anchor — these will be finalized in the Consolidate phase. + **Handling format placeholders:** The Roslyn source message may contain interpolation markers like `'{0}'`, `'{1}'`, etc. Replace these with descriptive terms that keep the text as close to the verbatim message as possible for SEO, while still reading as a coherent sentence. Use generic terms like `'type'`, `'value'`, `'operator'`, `'member'`, or `'method'` based on the context of the error. For example, `Constant value '{0}' cannot be converted to a '{1}'` becomes `Constant value 'value' cannot be converted to a 'type'`. Look at the XML `` element following the `` (if present) for hints about what each placeholder represents. + +**Content:** +- Add the source file's content as a new H2 section at the end of the destination file: + ```markdown + ## CS{NNNN} + + {source article content, adapted to fit as a section rather than standalone article} + ``` + Remove any front matter, H1 heading, and `See also` sections from the pasted content. Adjust heading levels (H2 in the source becomes H3, etc.). + +### 3. Create a redirect + +Use the `create-redirect-entry.ps1` script to add a redirect from the source file to the destination: + +```powershell +./.github/skills/redirect-article/scripts/create-redirect-entry.ps1 ` + -RedirectionFile ".openpublishing.redirection.csharp.json" ` + -SourcePath "docs/csharp/language-reference/compiler-messages/{source-filename}" ` + -RedirectUrl "/dotnet/csharp/language-reference/compiler-messages/{destination-filename-without-extension}" +``` + +If the source file is in `docs/csharp/misc/`, adjust the `SourcePath` accordingly. + +### 4. Update the TOC + +In `docs/csharp/language-reference/toc.yml`: +- Add the error code to the `displayName` for the destination file entry, maintaining numeric sort order. +- Find and remove the TOC entry for the source file (the `- name:` / `href:` block that references it). + +### 5. Delete the source file + +Delete the source markdown file from the repository. + +## After processing all files + +Present a summary: +- List of all source files merged +- Count of error codes added to the destination +- List of redirects created +- List of TOC entries removed + +Do not proceed to searching or consolidation — those are separate prompt files. diff --git a/.github/prompts/ErrorConsolidation.3.Search.prompt.md b/.github/prompts/ErrorConsolidation.3.Search.prompt.md new file mode 100644 index 0000000000000..8ebb2fb974048 --- /dev/null +++ b/.github/prompts/ErrorConsolidation.3.Search.prompt.md @@ -0,0 +1,91 @@ +--- +model: Claude Opus 4.6 (copilot) +agent: agent +description: Searches existing docs and Roslyn source for additional related error codes +tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'todo'] +--- + +# Search for additional related error codes + +You are searching for error codes related to a theme that may have been missed during initial consolidation. The user will provide: + +- **Destination filename** — the consolidated `.md` file in `docs/csharp/language-reference/compiler-messages/` +- **Theme description** — the theme to search for + +## Key file locations + +- **Destination file**: `docs/csharp/language-reference/compiler-messages/{destination-filename}` +- **TOC file**: `docs/csharp/language-reference/toc.yml` +- **Catch-all file**: `docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md` +- **Roslyn ErrorCodes**: `../roslyn/src/Compilers/CSharp/Portable/Errors/ErrorCodes.cs` +- **Roslyn Resources**: `../roslyn/src/Compilers/CSharp/Portable/CSharpResources.resx` + +## Phase A: Search existing documentation + +1. Read the destination file to collect all error codes already included. +2. Search all files whose names start with `cs` in these folders: + - `docs/csharp/language-reference/compiler-messages/` + - `docs/csharp/misc/` +3. For each candidate file, read its content and determine whether the error it documents relates to the theme. +4. Build a list of candidate files with their error codes and a brief reason why they match. + +**Present the candidate list to the user and stop.** Format the list as: + +``` +| File | Error Code | Reason | +|------|-----------|--------| +| cs0220.md | CS0220 | Describes compile-time overflow | +``` + +Tell the user: *Review this list. Approve the files you want merged, then run `ErrorConsolidation.2.MergeExisting` with the approved list.* + +**Wait for the user to respond before proceeding to Phase B.** + +## Phase B: Search undocumented errors in the catch-all file + +1. Read the `f1_keywords` front matter from `docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md`. +2. For each error code listed: + a. Extract the numeric portion (e.g., `CS0463` → `463`). + b. Find the constant with that number in `ErrorCodes.cs`. The constant will look like `ERR_SomeName = NNNN` or `WRN_SomeName = NNNN`. + c. Find the corresponding `` element in `CSharpResources.resx` whose `name` attribute matches the constant name (e.g., `ERR_SomeName`). + d. Read the verbatim error message from the `` child element. +3. Filter the results to only those whose error message relates to the theme. +4. Exclude any codes already in the destination file. + +**Present the filtered list to the user and stop.** Format as: + +``` +| Error Code | Error Message | +|-----------|--------------| +| CS0463 | Evaluation of the decimal constant expression failed | +| CS1021 | Integral constant is too large | +``` + +Tell the user: *Review this list. Tell me which error codes to add.* + +**Wait for the user to respond before proceeding to Phase C.** + +## Phase C: Batch add approved error codes + +For each approved error code: + +1. **Update destination front matter:** + - Add the code to `f1_keywords` in sorted numeric order. + - Add the code to `helpviewer_keywords` in sorted numeric order. + +2. **Update the error list** in the destination file body: + - Add an entry in sorted numeric order: + ``` + - [**CS{NNNN}**](#anchor-tbd): *{verbatim error message from CSharpResources.resx}* + **Handling format placeholders:** The Roslyn source message may contain interpolation markers like `'{0}'`, `'{1}'`, etc. Replace these with descriptive terms that keep the text as close to the verbatim message as possible for SEO, while still reading as a coherent sentence. Use generic terms like `'type'`, `'value'`, `'operator'`, `'member'`, or `'method'` based on the context of the error. For example, `Constant value '{0}' cannot be converted to a '{1}'` becomes `Constant value 'value' cannot be converted to a 'type'`. Look at the XML `` element following the `` (if present) for hints about what each placeholder represents. + ``` + +3. **Update the TOC:** + - Add the code to the `displayName` for the destination file entry in `docs/csharp/language-reference/toc.yml`, maintaining numeric sort order. + +4. **Remove from catch-all file:** + - Remove the code from `f1_keywords` in `docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md`. + +No redirections are needed for these error codes — they had no standalone articles. + +Present a summary of all changes made. diff --git a/.github/prompts/ErrorConsolidation.4.Consolidate.prompt.md b/.github/prompts/ErrorConsolidation.4.Consolidate.prompt.md new file mode 100644 index 0000000000000..a36ac96bde93e --- /dev/null +++ b/.github/prompts/ErrorConsolidation.4.Consolidate.prompt.md @@ -0,0 +1,98 @@ +--- +model: Claude Opus 4.6 (copilot) +agent: agent +description: Reorganizes individual error H2s into thematic sections with resolution focus +tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'todo'] +--- + +# Consolidate error sections and rewrite for resolution + +You are reorganizing a consolidated error article so individual per-error H2s become thematic H2 sections focused on resolution. The user will provide: + +- **Destination filename** — the consolidated `.md` file in `docs/csharp/language-reference/compiler-messages/` + +## Key file locations + +- **Destination file**: `docs/csharp/language-reference/compiler-messages/{destination-filename}` +- **Reference examples**: Other `*-errors.md` files in the same folder (study these for structural patterns) + +## Phase A: Propose themes + +1. Read the destination file and identify all error codes and their current H2 sections. +2. Read 2-3 other consolidated error files in `docs/csharp/language-reference/compiler-messages/` to understand the expected structure and tone. +3. Group the error codes into themes based on their error messages, underlying language rules, and resolution strategies. Each theme should represent a coherent set of related diagnostics. +4. Propose the list of themes with: + - A theme title (which becomes the H2 heading and anchor) + - The included error codes + - A one-sentence rationale for the grouping + +**Present the theme list to the user and stop.** Format as: + +``` +### Proposed themes + +1. **Operator signature requirements** (`#operator-signature-requirements`) + - CS0448, CS0559, CS0562, CS0563, CS0564, CS0567, CS0590 + - These errors all relate to invalid parameter or return types in operator declarations. + +2. **Overflow and underflow errors** (`#overflow-and-underflow-errors`) + - CS0031, CS0220, CS0221, CS0463, CS0543, CS0594, CS0652, CS1021, CS8778, CS8973 + - These errors all involve constant values or operations that exceed type boundaries. +``` + +Tell the user: *Review and approve each theme. Let me know which to proceed with and any adjustments.* + +**Wait for user approval before proceeding to Phase B.** + +## Phase B: Build thematic sections + +For each approved theme: + +### 1. Update the master error list at the top of the file + +Each error code in the master list should link to its theme's anchor. Keep the list in **numerical order** by error code. Format: + +```markdown +- [**CS{NNNN}**](#{theme-anchor}): *{verbatim compiler error message}* +``` + +### 2. Create the thematic H2 section + +Replace all the individual-error H2s that belong to this theme with a single thematic H2: + +```markdown +## {Theme title} + +- **CS{NNNN}**: *{verbatim error message}* +- **CS{NNNN}**: *{verbatim error message}* +... + +{Resolution-focused content} +``` + +The error list within the section repeats the codes and messages but **without anchor links** (they're already in the section). + +### 3. Write resolution-focused content + +The content in each thematic section should focus on **how to correct each error**, not on explaining the language feature. Follow these rules: + +- **Link to language reference:** Provide links to language reference articles and C# specification sections that explain the rules these diagnostics enforce. For example, link to `https://github.com/dotnet/docs/blob/main/docs/csharp/language-reference/operators/operator-overloading.md` or the relevant spec section. +- **Write detailed corrections:** For each correction, use a full sentence explaining what to do and why. Put the affected error codes in parentheses, in **bold** style. Example: + > Change the return type of `++` or `--` operators to the containing type or a type derived from it (**CS0448**). The language requires that increment and decrement operators return a value compatible with the containing type so the result can be assigned back to the same variable. +- **No extensive examples:** Remove lengthy code examples. Brief inline code references are acceptable. +- **No H3 headings:** Keep the section flat under the H2. +- **Note obsolete errors:** If any error codes are no longer produced in the latest version of C#, explicitly note that. +- **Incorporate source material:** Where applicable, reuse text or brief examples from the individual H2s you're replacing. + +### 4. Remove the old individual H2s + +After creating the thematic section, delete all individual-error H2s (`## CS{NNNN}`) that were absorbed into it. + +## Final check + +After all themes are built: + +1. Verify the master error list at the top is still in numerical order. +2. Verify every error code in the front matter has a corresponding entry in the master list. +3. Verify every error code in the master list links to a valid anchor in the article. +4. Verify there are no orphaned H2 sections (individual error H2s that weren't grouped into a theme). diff --git a/.github/prompts/ErrorConsolidation.5.Verify.prompt.md b/.github/prompts/ErrorConsolidation.5.Verify.prompt.md new file mode 100644 index 0000000000000..682e1523f4118 --- /dev/null +++ b/.github/prompts/ErrorConsolidation.5.Verify.prompt.md @@ -0,0 +1,76 @@ +--- +model: Claude Opus 4.6 (copilot) +agent: agent +description: Verifies all error messages in a consolidated article match Roslyn source verbatim +tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'todo'] +--- + +# Verify error messages against Roslyn source + +You are verifying that every error message in a consolidated compiler error article matches the verbatim text from the Roslyn compiler source. The user will provide: + +- **Destination filename** — the consolidated `.md` file in `docs/csharp/language-reference/compiler-messages/` + +## Key file locations + +- **Destination file**: `docs/csharp/language-reference/compiler-messages/{destination-filename}` +- **Roslyn ErrorCodes**: `../roslyn/src/Compilers/CSharp/Portable/Errors/ErrorCodes.cs` +- **Roslyn Resources**: `../roslyn/src/Compilers/CSharp/Portable/CSharpResources.resx` + +## Verification process + +### Step 1: Extract all error codes from the destination file + +Read the destination file and collect every error code referenced in: +- The master error list at the top of the article (the bulleted list after the H1) +- Any error lists within thematic H2 sections + +### Step 2: Look up each error message in Roslyn source + +For each error code: + +1. Extract the numeric portion (e.g., `CS0220` → `220`). +2. Find the constant with that number in `ErrorCodes.cs`. It will appear as something like: + ```csharp + ERR_CheckedOverflow = 220, + ``` +3. Find the corresponding `` element in `CSharpResources.resx` whose `name` attribute matches the constant name exactly (e.g., `ERR_CheckedOverflow`): + ```xml + + The operation overflows at compile time in checked mode + + ``` +4. Extract the text from the `` element. This is the **verbatim** compiler error message. + +**Note on format strings:** Some error messages contain placeholders like `'{0}'`, `'{1}'`, `{0}`, `{1}`, etc. In the documentation, these are typically replaced with descriptive terms like `'value'`, `'type'`, `'operator'`, etc. When comparing, treat placeholder substitutions as matches — only flag differences in the static text portions of the message. + +### Step 3: Compare and report + +Compare each Roslyn source message against every instance of that error's message in the destination file (both the master list and the thematic section lists). + +Build a report of mismatches: + +``` +| Error Code | Location | Current Text | Roslyn Source Text | +|-----------|----------|-------------|-------------------| +| CS0220 | Master list | The operation overflows at compile time | The operation overflows at compile time in checked mode | +| CS0220 | Overflow section | The operation overflows at compile time | The operation overflows at compile time in checked mode | +``` + +If there are no mismatches, report: *All error messages match the Roslyn source.* + +### Step 4: Fix mismatches + +For each mismatch found: + +1. Update the error message text in the destination file to match the Roslyn source verbatim. +2. Apply the fix in **all** locations where the message appears (master list, thematic section lists, and any inline references in the body text). +3. When replacing placeholders, use the same descriptive terms that appear in the current text (e.g., keep `'value'` for `'{0}'`) — only fix the static text portions. + +### Step 5: Present results + +After all fixes are applied, present: + +1. The total number of error codes verified. +2. The number of mismatches found and fixed. +3. A list of all corrections made, showing the before and after text. diff --git a/.github/prompts/error-consolidation.md b/.github/prompts/error-consolidation.md deleted file mode 100644 index 6a2eb3f1e43fa..0000000000000 --- a/.github/prompts/error-consolidation.md +++ /dev/null @@ -1,79 +0,0 @@ -# Copilot prompts to consolidate error codes. - -Overall steps: - -1. Make a new template, by hand. -1. Add any new errors that should be added here. -1. Consolidate existing errors, as identified by person. -1. Run Copilot search for other existing errors that person may have missed. -1. Search for missing errors. - -## Add a single existing file into the new consolidated article. - -We're going to work through a series of files consolidating errors and warnings. - -- For the duration of this chat, all references to "destination file" refer to `docs/csharp/language-reference/compiler-messages/overloaded-operator-errors.md`. -- For the duration of this chat, all references to "the target theme" refer to errors and warnings related to overflow, underflow, and checked and unchecked operators. - -The destination file already contains a skeleton for the final output. - -For each source file I specify in this chat, you'll do the following tasks: - -- Add the contents of the source file to the destination.md file. - - Include the source error code in the YML header for f1_keywords and helpviewer_keywords. - - Add an entry with an anchor for the error error code and its corresponding error message. The error message should be the verbatim compiler error message. - - Add the contents of the source file as a new H2 in the destination file. - - Add a redirection for the source file in the file .openpublishing.redirection.csharp.json. Make the destination point to destination file. Place the new entry in sorted order based on 'source_path_from_root'. -- Update the TOC file: - - Add the error code to the list of display names in the TOC for the destination file, sorted by numeric error code. - - Remove the TOC entry for the source file. - - Finally, delete the source markdown file. - -## Search for other related articles that may be missed. - -First, let's find candidate source files. Search all files whose names start with "CS" in the docs/csharp/language-reference/compiler-messages and the docs/csharp/misc folder for any other errors and warnings that involve the target theme. Give me a list to review for possible additional consolidation. Don't make any edits until the originating user approves. - -## Final search in roslyn source - -Let's check undocumented errors and the roslyn source for any missing errors. For every error code listed in "sorry-we-don-t-have-specifics-on-this-csharp-error.md" under the `f1_keywords` front matter, do the following: -1. Find that number as a constant in `ErrorCodes.cs`. -2. Locate the corresponding `data` element in CSharpResources.resx. The `name` atttribute should match the number of the constant. -3. Read the error message found in the `` element that is a child of that `` element. -Give me a list of all error numbers and corresponding error messages that relate to the target theme. - -To make sure you've found all related errors, we'll check the source. Look in `CSharpResources.resx` for any elements where the `` element is a message related to the target theme. The symbolic constant for that value is in the `name` attribute on the parent `data` element. Find that value in `ErrorCodes.cs`. It will map to the compiler error code, where the code is "CS" followed by the number as a four digit number. Build a list of any related errors, but don't make any edits yet. - -I'll give you error codes one by one. For each, I want you to do the following: - -- Add the new error code to the front matter of the destination file, for both the `f1_keywords` and `helpview_keywords` table. -- Add the new error code and error message to the table at the top of the destination file. The error message should be the verbatim text from the compiler -- Add the new error code to the list of `displayName` elements in the TOC file entry for the destination file. -- Remove the new error code from the front matter in the file `csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-errors.md` file. - -Note that no redirections need to be added for these error codes. - -## Build consolidated sections - -For all remaining work, all edits will be in the target file. The final format should mirror the structure of the other target theme files in the docs/csharp/language-reference/compiler-messages folder. Every H2 is a theme, all anchors are for the theme, not an individual error code. - -To do that, make a new H2 section for the theme. Remove all the H2s for the individual error codes that are part of that theme. Where applicable, the new H2 can include text or examples from the H2s you remove. The new section should include links to language reference articles that discuss the feature or theme. - -The list of errors at the top of the file should remain in numerical order, so it's easy for readers to scan. Each impacted error code should now have a link to the anchor tag for the new section. Repeat the list in the new section, but without the anchors, as shown in the highlighted text. - -Understand these instructions, then suggest a list of themes and the included error codes. I'll approve each theme before you begin editing. - -## Move from description to resolution - -Rework the highlighted section so the focus is on how to correct each error. This article doesn't need to explain the associated language feature. Instead, in each section, provide links to language reference or language specification material that explains the rules violated when these diagnostics appear. Add explanatory context after each correction (in parentheses with the error code). Provided brief reasons why each correction is needed. Use detailed, sentence-style explanations rather than brief imperative statements. For each recommendation put the affected error codes in parentheses, and in **bold** style. Remove extensive examples. Remove all H3 headings in this section. If any errors are no longer produced in the latest version of C#, make a note of that. - -## Verify error messages - -For every line in this list, verify that the error message associated with this error code matches the verbatim text in CSharpResources.resx. You can find the mapping using ErrorCodes.cs: - -1. Find that number as a constant in `ErrorCodes.cs`. -2. Locate the corresponding `data` element in CSharpResources.resx. The `name` atttribute should match the number of the constant. -3. Read the error message found in the `` element that is a child of that `` element. - - - -Now, ensure every instance of an error message matches the text in the highlighted table. \ No newline at end of file diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml index 9ddab780107a4..4b524116e70b0 100644 --- a/.github/workflows/markdownlint.yml +++ b/.github/workflows/markdownlint.yml @@ -27,7 +27,7 @@ jobs: egress-policy: audit - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - uses: DavidAnson/markdownlint-cli2-action@07035fd053f7be764496c0f8d8f9f41f98305101 # v22.0.0 + - uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9 # v23.0.0 with: config: ".markdownlint-cli2.jsonc" globs: "**/*.md" diff --git a/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.CustomEmbeddingsMiddle/ConsoleAI.CustomEmbeddingsMiddle.csproj b/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.CustomEmbeddingsMiddle/ConsoleAI.CustomEmbeddingsMiddle.csproj index 7d4a146dfd518..5265f3286918a 100644 --- a/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.CustomEmbeddingsMiddle/ConsoleAI.CustomEmbeddingsMiddle.csproj +++ b/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.CustomEmbeddingsMiddle/ConsoleAI.CustomEmbeddingsMiddle.csproj @@ -8,9 +8,9 @@ - - - + + + diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 2f01b4c76755d..4f9e98a7d8b92 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -57,7 +57,7 @@ | Health Insights Cancer Profiling | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Health.Insights.CancerProfiling/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Health.Insights.CancerProfiling-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.CancerProfiling_1.0.0-beta.1/sdk/healthinsights/Azure.Health.Insights.CancerProfiling/) | | Health Insights Clinical Matching | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Health.Insights.ClinicalMatching/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Health.Insights.ClinicalMatching-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.ClinicalMatching_1.0.0-beta.1/sdk/healthinsights/Azure.Health.Insights.ClinicalMatching/) | | Health Insights Radiology Insights | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Health.Insights.RadiologyInsights/1.1.0) | [docs](/dotnet/api/overview/azure/Health.Insights.RadiologyInsights-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.RadiologyInsights_1.1.0/sdk/healthinsights/Azure.Health.Insights.RadiologyInsights/) | -| Identity | NuGet [1.19.0](https://www.nuget.org/packages/Azure.Identity/1.19.0) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.19.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.19.0/sdk/identity/Azure.Identity/) | +| Identity | NuGet [1.20.0](https://www.nuget.org/packages/Azure.Identity/1.20.0) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.20.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.20.0/sdk/identity/Azure.Identity/) | | Identity Broker | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Identity.Broker/1.4.0) | [docs](/dotnet/api/overview/azure/Identity.Broker-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity.Broker_1.4.0/sdk/identity/Azure.Identity.Broker/) | | Image Analysis | NuGet [1.0.0](https://www.nuget.org/packages/Azure.AI.Vision.ImageAnalysis/1.0.0) | [docs](/dotnet/api/overview/azure/AI.Vision.ImageAnalysis-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Vision.ImageAnalysis_1.0.0/sdk/vision/Azure.AI.Vision.ImageAnalysis/) | | Key Vault - Administration | NuGet [4.7.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Administration/4.7.0) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Administration-readme) | GitHub [4.7.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Administration_4.7.0/sdk/keyvault/Azure.Security.KeyVault.Administration/) | @@ -84,7 +84,7 @@ | OpenAI Assistants | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.AI.OpenAI.Assistants/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/AI.OpenAI.Assistants-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.OpenAI.Assistants_1.0.0-beta.4/sdk/openai/Azure.AI.OpenAI.Assistants/) | | OpenAI Inference | NuGet [2.1.0](https://www.nuget.org/packages/Azure.AI.OpenAI/2.1.0)
NuGet [2.9.0-beta.1](https://www.nuget.org/packages/Azure.AI.OpenAI/2.9.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.OpenAI-readme) | GitHub [2.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.OpenAI_2.1.0/sdk/openai/Azure.AI.OpenAI/)
GitHub [2.9.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.OpenAI_2.9.0-beta.1/sdk/openai/Azure.AI.OpenAI/) | | OpenTelemetry AspNetCore | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore/1.4.0) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.AspNetCore-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.AspNetCore_1.4.0/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/) | -| OpenTelemetry Exporter | NuGet [1.6.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.6.0) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.Exporter-readme) | GitHub [1.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.6.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/) | +| OpenTelemetry Exporter | NuGet [1.7.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.7.0) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.Exporter-readme) | GitHub [1.7.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.7.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/) | | Personalizer | NuGet [2.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.Personalizer/2.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.Personalizer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [2.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Personalizer_2.0.0-beta.2/sdk/personalizer/Azure.AI.Personalizer/) | | Playwright | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Developer.Playwright/1.0.0) | [docs](/dotnet/api/overview/azure/Developer.Playwright-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Developer.Playwright_1.0.0/sdk/loadtestservice/Azure.Developer.Playwright/) | | Playwright NUnit | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Developer.Playwright.NUnit/1.0.0) | [docs](/dotnet/api/overview/azure/Developer.Playwright.NUnit-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Developer.Playwright.NUnit_1.0.0/sdk/loadtestservice/Azure.Developer.Playwright.NUnit/) | @@ -192,6 +192,7 @@ | Resource Management - App Configuration | NuGet [1.4.1](https://www.nuget.org/packages/Azure.ResourceManager.AppConfiguration/1.4.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppConfiguration-readme) | GitHub [1.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppConfiguration_1.4.1/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/) | | Resource Management - App Service | NuGet [1.4.1](https://www.nuget.org/packages/Azure.ResourceManager.AppService/1.4.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppService-readme) | GitHub [1.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppService_1.4.1/sdk/websites/Azure.ResourceManager.AppService/) | | Resource Management - Application Insights | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.ApplicationInsights/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ApplicationInsights/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ApplicationInsights-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApplicationInsights_1.0.1/sdk/applicationinsights/Azure.ResourceManager.ApplicationInsights/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApplicationInsights_1.1.0-beta.1/sdk/applicationinsights/Azure.ResourceManager.ApplicationInsights/) | +| Resource Management - Appnetwork | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.AppNetwork/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppNetwork-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppNetwork_1.0.0-beta.1/sdk/appnetwork/Azure.ResourceManager.AppNetwork/) | | Resource Management - Arizeaiobservabilityeval | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.ArizeAIObservabilityEval/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ArizeAIObservabilityEval-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ArizeAIObservabilityEval_1.0.0/sdk/arizeaiobservabilityeval/Azure.ResourceManager.ArizeAIObservabilityEval/) | | Resource Management - Artifactsigning | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.ArtifactSigning/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ArtifactSigning-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ArtifactSigning_1.0.0/sdk/artifactsigning/Azure.ResourceManager.ArtifactSigning/) | | Resource Management - Astro | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.Astro/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Astro-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Astro_1.0.0-beta.2/sdk/astronomer/Azure.ResourceManager.Astro/) | @@ -387,10 +388,10 @@ | Resource Management - Spring App Discovery | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.SpringAppDiscovery/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.SpringAppDiscovery-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SpringAppDiscovery_1.0.0-beta.2/sdk/springappdiscovery/Azure.ResourceManager.SpringAppDiscovery/) | | Resource Management - SQL | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.3.0)
NuGet [1.4.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.4.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.Sql-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.3.0/sdk/sqlmanagement/Azure.ResourceManager.Sql/)
GitHub [1.4.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.4.0-beta.3/sdk/sqlmanagement/Azure.ResourceManager.Sql/) | | Resource Management - SQL Virtual Machine | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.SqlVirtualMachine/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.SqlVirtualMachine-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SqlVirtualMachine_1.1.1/sdk/sqlvirtualmachine/Azure.ResourceManager.SqlVirtualMachine/) | -| Resource Management - Standby Pool | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.StandbyPool/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StandbyPool-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StandbyPool_1.1.0/sdk/standbypool/Azure.ResourceManager.StandbyPool/) | +| Resource Management - Standby Pool | NuGet [1.2.0](https://www.nuget.org/packages/Azure.ResourceManager.StandbyPool/1.2.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StandbyPool-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StandbyPool_1.2.0/sdk/standbypool/Azure.ResourceManager.StandbyPool/) | | Resource Management - Storage | NuGet [1.6.1](https://www.nuget.org/packages/Azure.ResourceManager.Storage/1.6.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Storage-readme) | GitHub [1.6.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Storage_1.6.1/sdk/storage/Azure.ResourceManager.Storage/) | | Resource Management - Storage Actions | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.StorageActions/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageActions-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageActions_1.0.0/sdk/storageactions/Azure.ResourceManager.StorageActions/) | -| Resource Management - Storage Cache | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.StorageCache/1.4.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageCache-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageCache_1.4.0/sdk/storagecache/Azure.ResourceManager.StorageCache/) | +| Resource Management - Storage Cache | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.StorageCache/1.4.0)
NuGet [1.5.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.StorageCache/1.5.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageCache-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageCache_1.4.0/sdk/storagecache/Azure.ResourceManager.StorageCache/)
GitHub [1.5.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageCache_1.5.0-beta.1/sdk/storagecache/Azure.ResourceManager.StorageCache/) | | Resource Management - Storage Mover | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.StorageMover/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageMover-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageMover_1.3.0/sdk/storagemover/Azure.ResourceManager.StorageMover/) | | Resource Management - Storage Pool | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.StoragePool/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StoragePool-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StoragePool_1.1.1/sdk/storagepool/Azure.ResourceManager.StoragePool/) | | Resource Management - Storage Sync | NuGet [1.3.1](https://www.nuget.org/packages/Azure.ResourceManager.StorageSync/1.3.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageSync-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageSync_1.3.1/sdk/storagesync/Azure.ResourceManager.StorageSync/) | @@ -412,13 +413,13 @@ | Resource Management - Workloadssapvirtualinstance | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.WorkloadsSapVirtualInstance/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.WorkloadsSapVirtualInstance-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.WorkloadsSapVirtualInstance_1.0.0-beta.1/sdk/workloadssapvirtualinstance/Azure.ResourceManager.WorkloadsSapVirtualInstance/) | | App Configuration Extension | NuGet [8.5.0](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.Functions.Worker/8.5.0)
NuGet [8.6.0-preview](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.Functions.Worker/8.6.0-preview) | | | | App Configuration Provider | NuGet [8.5.0](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.AspNetCore/8.5.0)
NuGet [8.6.0-preview](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.AspNetCore/8.6.0-preview) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp/1.0.0)
NuGet [2.0.0-beta.34](https://www.nuget.org/packages/Azure.Mcp/2.0.0-beta.34) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/1.0.0)
NuGet [2.0.0-beta.34](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/2.0.0-beta.34) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-x64/1.0.0)
NuGet [2.0.0-beta.34](https://www.nuget.org/packages/Azure.Mcp.linux-x64/2.0.0-beta.34) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/1.0.0)
NuGet [2.0.0-beta.34](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/2.0.0-beta.34) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-x64/1.0.0)
NuGet [2.0.0-beta.34](https://www.nuget.org/packages/Azure.Mcp.osx-x64/2.0.0-beta.34) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-arm64/1.0.0)
NuGet [2.0.0-beta.34](https://www.nuget.org/packages/Azure.Mcp.win-arm64/2.0.0-beta.34) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-x64/1.0.0)
NuGet [2.0.0-beta.34](https://www.nuget.org/packages/Azure.Mcp.win-x64/2.0.0-beta.34) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp/1.0.0)
NuGet [2.0.0-beta.35](https://www.nuget.org/packages/Azure.Mcp/2.0.0-beta.35) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/1.0.0)
NuGet [2.0.0-beta.35](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/2.0.0-beta.35) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-x64/1.0.0)
NuGet [2.0.0-beta.35](https://www.nuget.org/packages/Azure.Mcp.linux-x64/2.0.0-beta.35) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/1.0.0)
NuGet [2.0.0-beta.35](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/2.0.0-beta.35) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-x64/1.0.0)
NuGet [2.0.0-beta.35](https://www.nuget.org/packages/Azure.Mcp.osx-x64/2.0.0-beta.35) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-arm64/1.0.0)
NuGet [2.0.0-beta.35](https://www.nuget.org/packages/Azure.Mcp.win-arm64/2.0.0-beta.35) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-x64/1.0.0)
NuGet [2.0.0-beta.35](https://www.nuget.org/packages/Azure.Mcp.win-x64/2.0.0-beta.35) | | | | Azure MCP Types Internal | NuGet [0.2.804](https://www.nuget.org/packages/Microsoft.Azure.Mcp.AzTypes.Internal.Compact/0.2.804) | | | | Azure.Communication.Administration | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Administration/1.0.0-beta.3) | | | | Caching - PostgreSQL | NuGet [1.2.2](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Postgres/1.2.2) | | | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index 0ed06fe5022f0..870db6e74a791 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -61,7 +61,7 @@ | Health Insights Cancer Profiling | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Health.Insights.CancerProfiling/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Health.Insights.CancerProfiling-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.CancerProfiling_1.0.0-beta.1/sdk/healthinsights/Azure.Health.Insights.CancerProfiling/) | | Health Insights Clinical Matching | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Health.Insights.ClinicalMatching/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Health.Insights.ClinicalMatching-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.ClinicalMatching_1.0.0-beta.1/sdk/healthinsights/Azure.Health.Insights.ClinicalMatching/) | | Health Insights Radiology Insights | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Health.Insights.RadiologyInsights/1.1.0) | [docs](/dotnet/api/overview/azure/Health.Insights.RadiologyInsights-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.RadiologyInsights_1.1.0/sdk/healthinsights/Azure.Health.Insights.RadiologyInsights/) | -| Identity | NuGet [1.19.0](https://www.nuget.org/packages/Azure.Identity/1.19.0) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.19.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.19.0/sdk/identity/Azure.Identity/) | +| Identity | NuGet [1.20.0](https://www.nuget.org/packages/Azure.Identity/1.20.0) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.20.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.20.0/sdk/identity/Azure.Identity/) | | Identity Broker | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Identity.Broker/1.4.0) | [docs](/dotnet/api/overview/azure/Identity.Broker-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity.Broker_1.4.0/sdk/identity/Azure.Identity.Broker/) | | Image Analysis | NuGet [1.0.0](https://www.nuget.org/packages/Azure.AI.Vision.ImageAnalysis/1.0.0) | [docs](/dotnet/api/overview/azure/AI.Vision.ImageAnalysis-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Vision.ImageAnalysis_1.0.0/sdk/vision/Azure.AI.Vision.ImageAnalysis/) | | Key Vault - Administration | NuGet [4.7.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Administration/4.7.0) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Administration-readme) | GitHub [4.7.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Administration_4.7.0/sdk/keyvault/Azure.Security.KeyVault.Administration/) | @@ -92,7 +92,7 @@ | OpenAI Assistants | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.AI.OpenAI.Assistants/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/AI.OpenAI.Assistants-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.OpenAI.Assistants_1.0.0-beta.4/sdk/openai/Azure.AI.OpenAI.Assistants/) | | OpenAI Inference | NuGet [2.1.0](https://www.nuget.org/packages/Azure.AI.OpenAI/2.1.0)
NuGet [2.9.0-beta.1](https://www.nuget.org/packages/Azure.AI.OpenAI/2.9.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.OpenAI-readme) | GitHub [2.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.OpenAI_2.1.0/sdk/openai/Azure.AI.OpenAI/)
GitHub [2.9.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.OpenAI_2.9.0-beta.1/sdk/openai/Azure.AI.OpenAI/) | | OpenTelemetry AspNetCore | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore/1.4.0) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.AspNetCore-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.AspNetCore_1.4.0/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/) | -| OpenTelemetry Exporter | NuGet [1.6.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.6.0) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.Exporter-readme) | GitHub [1.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.6.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/) | +| OpenTelemetry Exporter | NuGet [1.7.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.7.0) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.Exporter-readme) | GitHub [1.7.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.7.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/) | | OpenTelemetry LiveMetrics | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.LiveMetrics/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.LiveMetrics-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.LiveMetrics_1.0.0-beta.3/sdk/monitor/Azure.Monitor.OpenTelemetry.LiveMetrics/) | | Personalizer | NuGet [2.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.Personalizer/2.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.Personalizer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [2.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Personalizer_2.0.0-beta.2/sdk/personalizer/Azure.AI.Personalizer/) | | Playwright | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Developer.Playwright/1.0.0) | [docs](/dotnet/api/overview/azure/Developer.Playwright-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Developer.Playwright_1.0.0/sdk/loadtestservice/Azure.Developer.Playwright/) | @@ -206,6 +206,7 @@ | Resource Management - App Platform | NuGet [1.1.2](https://www.nuget.org/packages/Azure.ResourceManager.AppPlatform/1.1.2) | [docs](/dotnet/api/overview/azure/ResourceManager.AppPlatform-readme) | GitHub [1.1.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppPlatform_1.1.2/sdk/appplatform/Azure.ResourceManager.AppPlatform/) | | Resource Management - App Service | NuGet [1.4.1](https://www.nuget.org/packages/Azure.ResourceManager.AppService/1.4.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppService-readme) | GitHub [1.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppService_1.4.1/sdk/websites/Azure.ResourceManager.AppService/) | | Resource Management - Application Insights | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.ApplicationInsights/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ApplicationInsights/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ApplicationInsights-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApplicationInsights_1.0.1/sdk/applicationinsights/Azure.ResourceManager.ApplicationInsights/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApplicationInsights_1.1.0-beta.1/sdk/applicationinsights/Azure.ResourceManager.ApplicationInsights/) | +| Resource Management - Appnetwork | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.AppNetwork/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppNetwork-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppNetwork_1.0.0-beta.1/sdk/appnetwork/Azure.ResourceManager.AppNetwork/) | | Resource Management - Arc ScVmm | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.ArcScVmm/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.ArcScVmm-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ArcScVmm_1.0.0-beta.4/sdk/arc-scvmm/Azure.ResourceManager.ArcScVmm/) | | Resource Management - Arizeaiobservabilityeval | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.ArizeAIObservabilityEval/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ArizeAIObservabilityEval-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ArizeAIObservabilityEval_1.0.0/sdk/arizeaiobservabilityeval/Azure.ResourceManager.ArizeAIObservabilityEval/) | | Resource Management - Artifactsigning | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.ArtifactSigning/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ArtifactSigning-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ArtifactSigning_1.0.0/sdk/artifactsigning/Azure.ResourceManager.ArtifactSigning/) | @@ -410,10 +411,10 @@ | Resource Management - Spring App Discovery | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.SpringAppDiscovery/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.SpringAppDiscovery-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SpringAppDiscovery_1.0.0-beta.2/sdk/springappdiscovery/Azure.ResourceManager.SpringAppDiscovery/) | | Resource Management - SQL | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.3.0)
NuGet [1.4.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.4.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.Sql-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.3.0/sdk/sqlmanagement/Azure.ResourceManager.Sql/)
GitHub [1.4.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.4.0-beta.3/sdk/sqlmanagement/Azure.ResourceManager.Sql/) | | Resource Management - SQL Virtual Machine | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.SqlVirtualMachine/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.SqlVirtualMachine-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SqlVirtualMachine_1.1.1/sdk/sqlvirtualmachine/Azure.ResourceManager.SqlVirtualMachine/) | -| Resource Management - Standby Pool | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.StandbyPool/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StandbyPool-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StandbyPool_1.1.0/sdk/standbypool/Azure.ResourceManager.StandbyPool/) | +| Resource Management - Standby Pool | NuGet [1.2.0](https://www.nuget.org/packages/Azure.ResourceManager.StandbyPool/1.2.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StandbyPool-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StandbyPool_1.2.0/sdk/standbypool/Azure.ResourceManager.StandbyPool/) | | Resource Management - Storage | NuGet [1.6.1](https://www.nuget.org/packages/Azure.ResourceManager.Storage/1.6.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Storage-readme) | GitHub [1.6.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Storage_1.6.1/sdk/storage/Azure.ResourceManager.Storage/) | | Resource Management - Storage Actions | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.StorageActions/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageActions-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageActions_1.0.0/sdk/storageactions/Azure.ResourceManager.StorageActions/) | -| Resource Management - Storage Cache | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.StorageCache/1.4.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageCache-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageCache_1.4.0/sdk/storagecache/Azure.ResourceManager.StorageCache/) | +| Resource Management - Storage Cache | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.StorageCache/1.4.0)
NuGet [1.5.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.StorageCache/1.5.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageCache-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageCache_1.4.0/sdk/storagecache/Azure.ResourceManager.StorageCache/)
GitHub [1.5.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageCache_1.5.0-beta.1/sdk/storagecache/Azure.ResourceManager.StorageCache/) | | Resource Management - Storage Mover | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.StorageMover/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageMover-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageMover_1.3.0/sdk/storagemover/Azure.ResourceManager.StorageMover/) | | Resource Management - Storage Pool | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.StoragePool/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StoragePool-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StoragePool_1.1.1/sdk/storagepool/Azure.ResourceManager.StoragePool/) | | Resource Management - Storage Sync | NuGet [1.3.1](https://www.nuget.org/packages/Azure.ResourceManager.StorageSync/1.3.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageSync-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageSync_1.3.1/sdk/storagesync/Azure.ResourceManager.StorageSync/) | diff --git a/docs/core/diagnostics/snippets/OTel-Prometheus-Grafana-Jaeger/csharp/OTel-Prometheus-Grafana-Jaeger.csproj b/docs/core/diagnostics/snippets/OTel-Prometheus-Grafana-Jaeger/csharp/OTel-Prometheus-Grafana-Jaeger.csproj index eeb44212991e2..08773410d7ed5 100644 --- a/docs/core/diagnostics/snippets/OTel-Prometheus-Grafana-Jaeger/csharp/OTel-Prometheus-Grafana-Jaeger.csproj +++ b/docs/core/diagnostics/snippets/OTel-Prometheus-Grafana-Jaeger/csharp/OTel-Prometheus-Grafana-Jaeger.csproj @@ -13,11 +13,11 @@ - - + + - - + + diff --git a/docs/core/extensions/snippets/logging/getting-started-open-telemetry/getting-started-open-telemetry.csproj b/docs/core/extensions/snippets/logging/getting-started-open-telemetry/getting-started-open-telemetry.csproj index f7028e9831461..75b271600d733 100644 --- a/docs/core/extensions/snippets/logging/getting-started-open-telemetry/getting-started-open-telemetry.csproj +++ b/docs/core/extensions/snippets/logging/getting-started-open-telemetry/getting-started-open-telemetry.csproj @@ -9,7 +9,7 @@ - + diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index 81815130adb04..d4abe245782ad 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -1,9 +1,10 @@ --- title: MSBuild properties for Microsoft.NET.Sdk description: Reference for the MSBuild properties and items that are understood by the .NET SDK. -ms.date: 03/03/2026 +ms.date: 03/27/2026 ms.topic: reference ms.custom: updateeachrelease +ai-usage: ai-assisted --- # MSBuild reference for .NET SDK projects @@ -1716,9 +1717,30 @@ The `EnableDynamicLoading` property indicates that an assembly is a dynamically The following properties concern code in generated files: +- [CompilerGeneratedFilesOutputPath](#compilergeneratedfilesoutputpath) - [DisableImplicitNamespaceImports](#disableimplicitnamespaceimports) +- [EmitCompilerGeneratedFiles](#emitcompilergeneratedfiles) - [ImplicitUsings](#implicitusings) +### CompilerGeneratedFilesOutputPath + +The `CompilerGeneratedFilesOutputPath` property specifies the directory where source generator output files are written when [EmitCompilerGeneratedFiles](#emitcompilergeneratedfiles) is set to `true`. The path can be absolute or relative to the project directory. If you don't set this property, the generated files are placed in a *generated* subdirectory under the intermediate output path (usually *obj/\/\/generated*). + +```xml + + true + Generated + +``` + +If you set this property to a path inside your project's source tree, the generated files might be picked up as source files by future builds. To avoid double-compilation, exclude the generated files from the `Compile` item: + +```xml + + + +``` + ### DisableImplicitNamespaceImports The `DisableImplicitNamespaceImports` property can be used to disable implicit namespace imports in Visual Basic projects that target .NET 6 or a later version. Implicit namespaces are the default namespaces that are imported globally in a Visual Basic project. Set this property to `true` to disable implicit namespace imports. @@ -1729,6 +1751,20 @@ The `DisableImplicitNamespaceImports` property can be used to disable implicit n ``` +### EmitCompilerGeneratedFiles + +The `EmitCompilerGeneratedFiles` property controls whether source generator output files are written to disk during the build. Set this property to `true` to enable this behavior. By default, source generator output exists only in memory and isn't written to disk. + +```xml + + true + +``` + +When you set this property to `true`, the generated files are placed in a *generated* subdirectory under the intermediate output path (usually *obj/\/\/generated*) unless you specify a different location using the [CompilerGeneratedFilesOutputPath](#compilergeneratedfilesoutputpath) property. + +Writing generated files to disk lets you inspect them. Only commit generated files to source control when you have a specific reason, such as when generators aren't available in your build environment or when you need reviewed, deterministic generated artifacts. + ### ImplicitUsings The `ImplicitUsings` property can be used to enable and disable implicit `global using` directives in C# projects that target .NET 6 or a later version and C# 10 or a later version. When the feature is enabled, the .NET SDK adds `global using` directives for a set of default namespaces based on the type of project SDK. Set this property to `true` or `enable` to enable implicit `global using` directives. To disable implicit `global using` directives, remove the property or set it to `false` or `disable`. @@ -1750,6 +1786,7 @@ To define an explicit `global using` directive, add a [Using](#using) item. - [AssemblyMetadata](#assemblymetadata) - [InternalsVisibleTo](#internalsvisibleto) +- [FrameworkReference](#frameworkreference) - [PackageReference](#packagereference) - [TrimmerRootAssembly](#trimmerrootassembly) - [Using](#using) diff --git a/docs/csharp/index.yml b/docs/csharp/index.yml index 3518707658648..dafbf61932135 100644 --- a/docs/csharp/index.yml +++ b/docs/csharp/index.yml @@ -32,7 +32,7 @@ highlightedContent: # Card - title: What's new itemType: whats-new - url: ./whats-new/csharp-14.md + url: ./whats-new/csharp-15.md # Card - title: Learn C# video series itemType: video diff --git a/docs/fsharp/get-started/get-started-vscode.md b/docs/fsharp/get-started/get-started-vscode.md index e8f8a5c9217e8..4cd5d81861396 100644 --- a/docs/fsharp/get-started/get-started-vscode.md +++ b/docs/fsharp/get-started/get-started-vscode.md @@ -10,28 +10,47 @@ You can write F# in [Visual Studio Code](https://code.visualstudio.com) with the > [!NOTE] > Before beginning, ensure you've installed both [F# and the Ionide plugin](install-fsharp.md#install-f-with-visual-studio-code). -## Create your first project with Ionide +## Explore F# with scripts and the REPL -To create a new F# project, open a command line and create a new project with the .NET CLI: +The fastest way to start writing F# is with a script file (`.fsx`) and F# Interactive (FSI). No project files or build setup are needed — just create a file and start coding, similar to how you might use Python or a shell script. -```dotnetcli -dotnet new console -lang "F#" -o FirstIonideProject -``` +### Create and run a script -Once it completes, change directory to the project and open Visual Studio Code: +Open a terminal and run: ```console -cd FirstIonideProject -code . +touch hello.fsx +code hello.fsx ``` -After the project loads in Visual Studio Code, you should see the F# Solution Explorer pane on the left-hand side of your window open. This means Ionide has successfully loaded the project you just created. You can write code in the editor before this point in time, but once this happens, everything has finished loading. +Add the following code to the file: + +```fsharp +printfn "Hello from F# Interactive!" -### Write your first script +let square x = x * x + +[ 1 .. 10 ] +|> List.map square +|> printfn "Squares: %A" +``` + +Run the script directly from the terminal: + +```dotnetcli +dotnet fsi hello.fsx +``` + +You should see: + +```console +Hello from F# Interactive! +Squares: [1; 4; 9; 16; 25; 36; 49; 64; 81; 100] +``` -Once you've configured Visual Studio Code to use .NET Core scripting, navigate to the Explorer view in Visual Studio Code and create a new file. Name it *MyFirstScript.fsx*. +### Use the interactive REPL from VS Code -Now add the following code to it: +Scripts are especially powerful when combined with Ionide's FSI integration. Create a new file called *MyFirstScript.fsx* and add the following code: [!code-fsharp[ToPigLatin](~/samples/snippets/fsharp/getting-started/to-pig-latin.fsx)] @@ -76,6 +95,29 @@ The function appears to be working as expected. Congratulations, you just wrote > [!NOTE] > As you may have noticed, the lines in FSI are terminated with `;;`. This is because FSI allows you to enter multiple lines. The `;;` at the end lets FSI know when the code is finished. +### When to use scripts + +Scripts are great for exploring ideas, prototyping, data analysis, and automation tasks. You can reference NuGet packages directly in a script with `#r "nuget: PackageName"` — no project file needed. + +When your code grows beyond a single file or needs to be compiled and distributed, you'll want to move to a full project. The next section shows how. + +## Create your first project with Ionide + +For larger programs, compiled libraries, or code you want to distribute as an application, you'll use a .NET project. To create a new F# project, open a command line and create a new project with the .NET CLI: + +```dotnetcli +dotnet new console -lang "F#" -o FirstIonideProject +``` + +Once it completes, change directory to the project and open Visual Studio Code: + +```console +cd FirstIonideProject +code . +``` + +After the project loads in Visual Studio Code, you should see the F# Solution Explorer pane on the left-hand side of your window open. This means Ionide has successfully loaded the project you just created. You can write code in the editor before this point in time, but once this happens, everything has finished loading. + ## Explaining the code If you're not sure about what the code is actually doing, here's a step-by-step. diff --git a/docs/fsharp/get-started/index.md b/docs/fsharp/get-started/index.md index 9665c0ec32b53..b6cfc16eb49a8 100644 --- a/docs/fsharp/get-started/index.md +++ b/docs/fsharp/get-started/index.md @@ -19,6 +19,9 @@ There are multiple guides on how to install and use F# for the first time on you In general, there is no specific way that is better than the rest. We recommend trying all ways to use F# on your machine to see what you like the best! +> [!TIP] +> If you want to start exploring F# quickly without setting up a project, you can write F# scripts (`.fsx` files) and run them with `dotnet fsi`. The [Visual Studio Code guide](get-started-vscode.md#explore-f-with-scripts-and-the-repl) shows how to get started with scripts and the F# Interactive REPL. + ## Get started online If you'd rather not install F# and .NET on your machine, you can also get started with F# in the browser: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1822.md b/docs/fundamentals/code-analysis/quality-rules/ca1822.md index ba3816b03b8fe..66a4283aeb268 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1822.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1822.md @@ -1,7 +1,8 @@ --- title: "CA1822: Mark members as static (code analysis)" description: "Learn about code analysis rule CA1822: Mark members as static" -ms.date: 11/04/2016 +ms.date: 03/30/2026 +ai-usage: ai-assisted f1_keywords: - MarkMembersAsStatic - CA1822 @@ -41,7 +42,10 @@ Mark the member as static (or Shared in Visual Basic) or use 'this'/'Me' in the ## When to suppress warnings -It is safe to suppress a warning from this rule for previously shipped code for which the fix would be a breaking change. +It's safe to suppress a warning from this rule in the following cases: + +- For previously shipped code for which the fix would be a breaking change. +- For methods in classes that inherit from . The methods in these classes shouldn't be marked as static, because the .NET remoting infrastructure uses instance dispatch to forward calls across AppDomain boundaries. Making such methods static can break remoting across AppDomain boundaries. ## Suppress a warning diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2227.md b/docs/fundamentals/code-analysis/quality-rules/ca2227.md index 6f7ea9e7d1cf4..ec9a00749a0cd 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2227.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2227.md @@ -1,80 +1,87 @@ ---- -title: "CA2227: Collection properties should be read only (code analysis)" -description: "Learn about code analysis rule CA2227: Collection properties should be read only" -ms.date: 07/08/2021 -f1_keywords: -- CA2227 -- CollectionPropertiesShouldBeReadOnly -helpviewer_keywords: -- CA2227 -- CollectionPropertiesShouldBeReadOnly -author: gewarren -ms.author: gewarren -dev_langs: -- CSharp -- VB ---- -# CA2227: Collection properties should be read only - -| Property | Value | -|-------------------------------------|-------------------------------------------| -| **Rule ID** | CA2227 | -| **Title** | Collection properties should be read only | -| **Category** | [Usage](usage-warnings.md) | -| **Fix is breaking or non-breaking** | Breaking | -| **Enabled by default in .NET 10** | No | - -## Cause - -An externally visible, writable property is of a type that implements . This rule ignores arrays, indexers (properties with the name 'Item'), immutable collections, readonly collections, and permission sets. - -## Rule description - -A writable collection property allows a user to replace the collection with a completely different collection. A read-only or [init-only](../../../csharp/language-reference/keywords/init.md) property stops the collection from being replaced, but still allows the individual members to be set. If replacing the collection is a goal, the preferred design pattern is to include a method to remove all the elements from the collection, and a method to repopulate the collection. See the and methods of the class for an example of this pattern. - -Both binary and XML serialization support read-only properties that are collections. The class has specific requirements for types that implement and in order to be serializable. - -## How to fix violations - -To fix a violation of this rule, make the property read-only or [init-only](../../../csharp/language-reference/keywords/init.md). If the design requires it, add methods to clear and repopulate the collection. - -## When to suppress warnings - -You can suppress the warning if the property is part of a [Data Transfer Object (DTO)](/previous-versions/msp-n-p/ff649585(v=pandp.10)) class. - -Otherwise, do not suppress warnings from this rule. - -## Suppress a warning - -If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule. - -```csharp -#pragma warning disable CA2227 -// The code that's violating the rule is on this line. -#pragma warning restore CA2227 -``` - -To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md). - -```ini -[*.{cs,vb}] -dotnet_diagnostic.CA2227.severity = none -``` - -For more information, see [How to suppress code analysis warnings](../suppress-warnings.md). - -## Example - -The following example shows a type with a writable collection property and shows how the collection can be replaced directly. Additionally, it shows the preferred manner of replacing a read-only collection property using `Clear` and `AddRange` methods. - -:::code language="csharp" source="snippets/csharp/all-rules/ca2227.cs" id="snippet1"::: - -:::code language="vb" source="snippets/vb/all-rules/ca2227-collection-properties-should-be-read-only_1.vb"::: - -## Related rules - -- [CA1819: Properties should not return arrays](ca1819.md) - -## See also - -- [Properties in C#](../../../csharp/programming-guide/classes-and-structs/properties.md) +--- +title: "CA2227: Collection properties should be read only (code analysis)" +description: "Learn about code analysis rule CA2227: Collection properties should be read only" +ms.date: 03/30/2026 +f1_keywords: +- CA2227 +- CollectionPropertiesShouldBeReadOnly +helpviewer_keywords: +- CA2227 +- CollectionPropertiesShouldBeReadOnly +author: gewarren +ms.author: gewarren +ai-usage: ai-assisted +dev_langs: +- CSharp +- VB +--- +# CA2227: Collection properties should be read only + +| Property | Value | +|-------------------------------------|-------------------------------------------| +| **Rule ID** | CA2227 | +| **Title** | Collection properties should be read only | +| **Category** | [Usage](usage-warnings.md) | +| **Fix is breaking or non-breaking** | Breaking | +| **Enabled by default in .NET 10** | No | + +## Cause + +An externally visible, writable property is of a type that implements . This rule ignores arrays, indexers (properties with the name 'Item'), immutable collections, readonly collections, and permission sets. + +## Rule description + +A writable collection property lets users replace the collection with a completely different collection. A read-only or [init-only](../../../csharp/language-reference/keywords/init.md) property prevents the collection from being replaced, but still allows individual members to be set. If replacing the collection is a goal, the preferred design pattern is to include a method to remove all elements from the collection, and a method to repopulate the collection. See the and methods of the class for an example of this pattern. + +Both binary and XML serialization support read-only properties that are collections. The class has specific requirements for types that implement and to be serializable. + +## How to fix violations + +Use one of the following approaches to fix a violation of this rule: + +- **Make the property read-only or init-only.** A read-only or [init-only](../../../csharp/language-reference/keywords/init.md) property prevents the collection from being replaced while still allowing individual members to be set. If the design requires replacing the collection's contents, add methods to clear and repopulate the collection. For an example of this pattern, see the and methods. + +- **Change the property type to a read-only collection type.** If callers don't need to modify the collection, change the property type to a read-only collection, such as . This approach makes the read-only intent explicit in the type signature. + +- **Change the property type to a thread-safe concurrent collection type, while keeping the property read-only.** If the design requires multiple threads to modify the collection concurrently, expose a read-only property (no setter) whose type is a concurrent collection, such as . CA2227 is triggered by a writable collection property, not by the collection type, so the property must still be read-only. The concurrent collection choice only addresses thread-safe mutation of the returned collection instance. + +## When to suppress warnings + +You can suppress the warning if the property is part of a [Data Transfer Object (DTO)](/previous-versions/msp-n-p/ff649585(v=pandp.10)) class. + +Otherwise, don't suppress warnings from this rule. + +## Suppress a warning + +If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule. + +```csharp +#pragma warning disable CA2227 +// The code that's violating the rule is on this line. +#pragma warning restore CA2227 +``` + +To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md). + +```ini +[*.{cs,vb}] +dotnet_diagnostic.CA2227.severity = none +``` + +For more information, see [How to suppress code analysis warnings](../suppress-warnings.md). + +## Example + +The following example shows a type with a writable collection property and how you can replace the collection directly. It also shows the preferred way to replace a read-only collection property using `Clear` and `AddRange` methods. + +:::code language="csharp" source="snippets/csharp/all-rules/ca2227.cs" id="snippet1"::: + +:::code language="vb" source="snippets/vb/all-rules/ca2227-collection-properties-should-be-read-only_1.vb"::: + +## Related rules + +- [CA1819: Properties should not return arrays](ca1819.md) + +## See also + +- [Properties in C#](../../../csharp/programming-guide/classes-and-structs/properties.md) diff --git a/docs/fundamentals/runtime-libraries/system-string-intern.md b/docs/fundamentals/runtime-libraries/system-string-intern.md index a56be6242e76b..cf077060d9153 100644 --- a/docs/fundamentals/runtime-libraries/system-string-intern.md +++ b/docs/fundamentals/runtime-libraries/system-string-intern.md @@ -1,7 +1,8 @@ --- title: System.String.Intern method description: Learn about the System.String.Intern method. -ms.date: 01/24/2024 +ms.date: 03/27/2026 +ai-usage: ai-assisted dev_langs: - CSharp - FSharp @@ -11,11 +12,11 @@ dev_langs: [!INCLUDE [context](includes/context.md)] -The common language runtime conserves string storage by maintaining a table, called the *intern pool*, that contains a single reference to each unique literal string declared or created programmatically in your program. Consequently, an instance of a literal string with a particular value only exists once in the system. For example, if you assign the same literal string to several variables, the runtime retrieves the same reference to the literal string from the intern pool and assigns it to each variable. +The common language runtime maintains a table, called the *intern pool*, that holds a single reference for each unique string value. The method uses the intern pool to search for a string equal to the value of `str`. If no such string exists, a reference to `str` is added to the pool, and that reference is returned. (In contrast, the method returns a null reference if the requested string doesn't exist in the intern pool.) -The method uses the intern pool to search for a string equal to the value of its parameter, `str`. If such a string exists, its reference in the intern pool is returned. If the string does not exist, a reference to `str` is added to the intern pool, then that reference is returned. (In contrast, the method returns a null reference if the requested string doesn't exist in the intern pool.) +The intern pool can be used by the runtime to conserve string storage. However, automatic interning of string literals isn't guaranteed—depending on how the assembly was compiled and executed, some literals might not be added to the pool. -In the following example, the string `s1`, which has a value of "MyTest", is already interned because it is a literal in the program. The class generates a new string object that has the same value as `s1`. A reference to that string is assigned to `s2`. The method searches for a string that has the same value as `s2`. Because such a string exists, the method returns the same reference that's assigned to `s1`. That reference is then assigned to `s3`. References `s1` and `s2` compare unequal because they refer to different objects; references `s1` and `s3` compare equal because they refer to the same string. +In the following example, the string `s1` has a value of "MyTest". The class generates a new string object that has the same value as `s1`. A reference to that string is assigned to `s2`. The method searches for a string that has the same value as `s2`. If `s1` was already interned (for example, because the assembly requires string-literal interning), the method returns the same reference as `s1`, which is then assigned to `s3`, and `s1` and `s3` compare equal. Otherwise, a new interned entry is created for `s2` and assigned to `s3`, and `s1` and `s3` compare unequal. In either case, `s1` and `s2` compare unequal because they refer to different objects. :::code language="csharp" source="./snippets/System/String/Intern/csharp/Intern1.cs" id="Snippet1"::: :::code language="fsharp" source="./snippets/System/String/Intern/fsharp/Intern1.fs" id="Snippet1"::: @@ -25,4 +26,6 @@ In the following example, the string `s1`, which has a value of "MyTest", is alr If you're trying to reduce the total amount of memory your application allocates, keep in mind that interning a string has two unwanted side effects. First, the memory allocated for interned objects is not likely to be released until the common language runtime (CLR) terminates. The reason is that the CLR's reference to the interned object can persist after your application, or even your application domain, terminates. Second, to intern a string, you must first create the string. The memory used by the object must still be allocated, even though the memory will eventually be garbage collected. -The enumeration member marks an assembly as not requiring string-literal interning. You can apply to an assembly using the attribute. Also, when you use [Ngen.exe (Native Image Generator)](../../framework/tools/ngen-exe-native-image-generator.md) to compile an assembly in advance of runtime, strings are not interned across modules. +The enumeration member marks an assembly as not requiring string-literal interning. By default, the C# compiler emits a with the flag on each assembly for better performance, which means string literals are not guaranteed to be added to the intern pool. You can customize on an assembly using the attribute. + +When you publish an app using [native AOT](../../core/deploying/native-aot/index.md), turning off is not supported. With native AOT, string literals aren't guaranteed to be added to the intern pool, so might not find a match for a string that appears to be a literal in source code. diff --git a/docs/orleans/grains/snippets/transactions/Abstractions/Abstractions.csproj b/docs/orleans/grains/snippets/transactions/Abstractions/Abstractions.csproj index 1be0c74bd42ab..8a5cebd91519a 100644 --- a/docs/orleans/grains/snippets/transactions/Abstractions/Abstractions.csproj +++ b/docs/orleans/grains/snippets/transactions/Abstractions/Abstractions.csproj @@ -1,7 +1,7 @@ - + diff --git a/docs/orleans/grains/snippets/transactions/Client/Client.csproj b/docs/orleans/grains/snippets/transactions/Client/Client.csproj index 82981a2621d33..ac831ba575bdd 100644 --- a/docs/orleans/grains/snippets/transactions/Client/Client.csproj +++ b/docs/orleans/grains/snippets/transactions/Client/Client.csproj @@ -5,7 +5,7 @@ - + diff --git a/docs/orleans/grains/snippets/transactions/Server/Server.csproj b/docs/orleans/grains/snippets/transactions/Server/Server.csproj index 18b655fcc87e1..63c691ca5d28e 100644 --- a/docs/orleans/grains/snippets/transactions/Server/Server.csproj +++ b/docs/orleans/grains/snippets/transactions/Server/Server.csproj @@ -5,7 +5,7 @@ - + diff --git a/docs/standard/io/pipelines.md b/docs/standard/io/pipelines.md index 3993f48fa4537..909df470ae237 100644 --- a/docs/standard/io/pipelines.md +++ b/docs/standard/io/pipelines.md @@ -1,23 +1,21 @@ --- title: System.IO.Pipelines - .NET description: Learn how to efficiently use I/O pipelines in .NET and avoid problems in your code. -ms.date: 05/09/2022 +ms.date: 03/26/2026 helpviewer_keywords: - "Pipelines" - "Pipelines I/O" - "I/O [.NET], Pipelines" -author: rick-anderson +ai-usage: ai-assisted --- -# System.IO.Pipelines in .NET +# System.IO.Pipelines - is a library that is designed to make it easier to do high-performance I/O in .NET. It's a library targeting .NET Standard that works on all .NET implementations. + is a library designed to make high-performance I/O in .NET easier. The package targets .NET Standard for broad compatibility, .NET Framework, and modern .NET. In modern .NET versions, `System.IO.Pipelines` is included in the shared framework and doesn't require a separate NuGet package. -The library is available in the [System.IO.Pipelines](https://www.nuget.org/packages/System.IO.Pipelines) Nuget package. +The library is also available as the [System.IO.Pipelines](https://www.nuget.org/packages/System.IO.Pipelines) NuGet package. - - -## What problem does System.IO.Pipelines solve +## What problem does System.IO.Pipelines solve? Apps that parse streaming data are composed of boilerplate code having many specialized and unusual code flows. The boilerplate and special case code is complex and difficult to maintain. @@ -27,7 +25,7 @@ Apps that parse streaming data are composed of boilerplate code having many spec * Have high performance parsing streaming data. * Reduce code complexity. -The following code is typical for a TCP server that receives line-delimited messages (delimited by `'\n'`) from a client: +This code is typical for a TCP server that receives line-delimited messages (delimited by `'\n'`) from a client: ```csharp async Task ProcessLinesAsync(NetworkStream stream) @@ -47,17 +45,17 @@ The preceding code has several problems: * It doesn't handle the case where multiple lines are read in a single `ReadAsync` call. * It allocates a `byte` array with each read. -To fix the preceding problems, the following changes are required: +To fix the preceding problems, make these changes: * Buffer the incoming data until a new line is found. * Parse all the lines returned in the buffer. -* It's possible that the line is bigger than 1 KB (1024 bytes). The code needs to resize the input buffer until the delimiter is found in order to fit the complete line inside the buffer. +* The line might be bigger than 1 KB (1024 bytes). The code needs to resize the input buffer until the delimiter is found to fit the complete line inside the buffer. * If the buffer is resized, more buffer copies are made as longer lines appear in the input. * To reduce wasted space, compact the buffer used for reading lines. * Consider using buffer pooling to avoid allocating memory repeatedly. -* The following code addresses some of these problems: +* This code addresses some of these problems: :::code language="csharp" source="snippets/pipelines_1/ProcessLinesAsync.cs" id="snippet"::: @@ -65,22 +63,20 @@ The previous code is complex and doesn't address all the problems identified. Hi ## Pipe -The class can be used to create a `PipeWriter/PipeReader` pair. All data written into the `PipeWriter` is available in the `PipeReader`: +Use the class to create a `PipeWriter/PipeReader` pair. All data written into the `PipeWriter` is available in the `PipeReader`: :::code language="csharp" source="snippets/pipelines_1/Pipe.cs" id="snippet2"::: - - ### Pipe basic usage :::code language="csharp" source="snippets/pipelines_1/Pipe.cs" id="snippet"::: -There are two loops: +Two loops handle the reading and writing: * `FillPipeAsync` reads from the `Socket` and writes to the `PipeWriter`. * `ReadPipeAsync` reads from the `PipeReader` and parses incoming lines. -There are no explicit buffers allocated. All buffer management is delegated to the `PipeReader` and `PipeWriter` implementations. Delegating buffer management makes it easier for consuming code to focus solely on the business logic. +No explicit buffers are allocated. All buffer management is delegated to the `PipeReader` and `PipeWriter` implementations. Delegating buffer management makes it easier for consuming code to focus solely on the business logic. In the first loop: @@ -89,19 +85,19 @@ In the first loop: is called to tell the `PipeWriter` how much data was written to the buffer. * is called to make the data available to the `PipeReader`. -In the second loop, the `PipeReader` consumes the buffers written by `PipeWriter`. The buffers come from the socket. The call to `PipeReader.ReadAsync`: +In the second loop, the `PipeReader` consumes the buffers written by `PipeWriter`. The buffers come from the socket. The call to : * Returns a that contains two important pieces of information: - * The data that was read in the form of `ReadOnlySequence`. + * The data that was read in the form of . * A boolean `IsCompleted` that indicates if the end of data (EOF) has been reached. After finding the end of line (EOL) delimiter and parsing the line: * The logic processes the buffer to skip what's already processed. -* `PipeReader.AdvanceTo` is called to tell the `PipeReader` how much data has been consumed and examined. +* is called to tell the `PipeReader` how much data has been consumed and examined. -The reader and writer loops end by calling `Complete`. `Complete` lets the underlying Pipe release the memory it allocated. +The reader and writer loops end by calling and . Calling `Complete` releases the memory the underlying `Pipe` allocated. ### Backpressure and flow control @@ -120,7 +116,7 @@ For optimal performance, there's a balance between frequent pauses and allocatin To solve the preceding problem, the `Pipe` has two settings to control the flow of data: * : Determines how much data should be buffered before calls to pause. -* : Determines how much data the reader has to observe before calls to `PipeWriter.FlushAsync` resume. +* : Determines how much data the reader has to observe before calls to resume. ![Diagram with ResumeWriterThreshold and PauseWriterThreshold](media/pipelines/resume-pause.png) @@ -155,27 +151,27 @@ When doing I/O, it's important to have fine-grained control over where the I/O i ### Pipe reset -It's frequently efficient to reuse the `Pipe` object. To reset the pipe, call when both the `PipeReader` and `PipeWriter` are complete. +Reusing the `Pipe` object is often efficient. To reset the pipe, call when both the `PipeReader` and `PipeWriter` are complete. ## PipeReader - manages memory on the caller's behalf. **Always** call after calling . This lets the `PipeReader` know when the caller is done with the memory so that it can be tracked. The `ReadOnlySequence` returned from `PipeReader.ReadAsync` is only valid until the call the `PipeReader.AdvanceTo`. It's illegal to use `ReadOnlySequence` after calling `PipeReader.AdvanceTo`. + manages memory on the caller's behalf. **Always** call after calling . This lets the `PipeReader` know when the caller is done with the memory so that it can be tracked. The returned from is only valid until the call to . It's illegal to use after calling . -`PipeReader.AdvanceTo` takes two arguments: + takes two arguments: * The first argument determines how much memory was consumed. * The second argument determines how much of the buffer was observed. -Marking data as consumed means that the pipe can return the memory to the underlying buffer pool. Marking data as observed controls what the next call to `PipeReader.ReadAsync` does. Marking everything as observed means that the next call to `PipeReader.ReadAsync` won't return until there's more data written to the pipe. Any other value will make the next call to `PipeReader.ReadAsync` return immediately with the observed *and* unobserved data, but not data that has already been consumed. +Marking data as consumed means that the pipe can return the memory to the underlying buffer pool. Marking data as observed controls what the next call to does. Marking everything as observed means that the next call to won't return until there's more data written to the pipe. Any other value makes the next call to return immediately with the observed *and* unobserved data, but not data that has already been consumed. ### Read streaming data scenarios -There are a couple of typical patterns that emerge when trying to read streaming data: +A couple of typical patterns emerge when reading streaming data: * Given a stream of data, parse a single message. * Given a stream of data, parse all available messages. -The following examples use the `TryParseLines` method for parsing messages from a `ReadOnlySequence`. `TryParseLines` parses a single message and updates the input buffer to trim the parsed message from the buffer. `TryParseLines` isn't part of .NET, it's a user written method used in the following sections. +These examples use the `TryParseLines` method for parsing messages from a . `TryParseLines` parses a single message and updates the input buffer to trim the parsed message from the buffer. `TryParseLines` isn't part of .NET; it's a user-written method used in the following sections. ```csharp bool TryParseLines(ref ReadOnlySequence buffer, out Message message); @@ -183,7 +179,7 @@ bool TryParseLines(ref ReadOnlySequence buffer, out Message message); ### Read a single message -The following code reads a single message from a `PipeReader` and returns it to the caller. +This code reads a single message from a `PipeReader` and returns it to the caller. :::code language="csharp" source="snippets/pipelines_1/ReadSingleMsg.cs" id="snippet"::: @@ -197,45 +193,48 @@ The two `SequencePosition` arguments are updated because `TryParseLines` removes * The end of the message. * The end of the received buffer if no message was found. -The single message case has the most potential for errors. Passing the wrong values to *examined* can result in an out of memory exception or an infinite loop. For more information, see the [PipeReader common problems](#gotchas) section in this article. +The single message case has the most potential for errors. Passing the wrong values to *examined* might result in an out of memory exception or an infinite loop. For more information, see the [PipeReader common problems](#pipereader-common-problems) section in this article. + +> [!IMPORTANT] +> `ReadSingleMessageAsync` doesn't call `PipeReader.CompleteAsync`. The caller is responsible for completing the `PipeReader`. Calling `PipeReader.CompleteAsync` inside `ReadSingleMessageAsync` signals that no more data can be read, which prevents reading subsequent messages. -### Reading multiple messages +### Read multiple messages -The following code reads all messages from a `PipeReader` and calls `ProcessMessageAsync` on each. +This code reads all messages from a `PipeReader` and calls `ProcessMessageAsync` on each. :::code language="csharp" source="snippets/pipelines_1/MyConnection1.cs" id="snippet"::: +Because `ProcessMessagesAsync` owns the complete message-reading loop, it calls when it's done. Unlike the single-message case, the caller doesn't need to complete the reader. `ProcessMessagesAsync` takes full ownership of the `PipeReader` lifetime. + ### Cancellation -`PipeReader.ReadAsync`: +: * Supports passing a . * Throws an if the `CancellationToken` is canceled while there's a read pending. -* Supports a way to cancel the current read operation via , which avoids raising an exception. Calling `PipeReader.CancelPendingRead` causes the current or next call to `PipeReader.ReadAsync` to return a with `IsCanceled` set to `true`. This can be useful for halting the existing read loop in a non-destructive and non-exceptional way. +* Supports a way to cancel the current read operation via , which avoids raising an exception. Calling `PipeReader.CancelPendingRead` causes the current or next call to to return a with `IsCanceled` set to `true`. This is useful for halting the existing read loop in a non-destructive and non-exceptional way. :::code language="csharp" source="snippets/pipelines_1/MyConnection.cs" id="snippet"::: - - ### PipeReader common problems -* Passing the wrong values to `consumed` or `examined` may result in reading already read data. -* Passing `buffer.End` as examined may result in: +* Passing the wrong values to `consumed` or `examined` might result in reading already read data. +* Passing `buffer.End` as examined might result in: * Stalled data - * Possibly an eventual Out of Memory (OOM) exception if data isn't consumed. For example, `PipeReader.AdvanceTo(position, buffer.End)` when processing a single message at a time from the buffer. + * An eventual out-of-memory (OOM) exception if data isn't consumed. For example, `PipeReader.AdvanceTo(position, buffer.End)` when processing a single message at a time from the buffer. -* Passing the wrong values to `consumed` or `examined` may result in an infinite loop. For example, `PipeReader.AdvanceTo(buffer.Start)` if `buffer.Start` hasn't changed will cause the next call to `PipeReader.ReadAsync` to return immediately before new data arrives. -* Passing the wrong values to `consumed` or `examined` may result in infinite buffering (eventual OOM). -* Using the `ReadOnlySequence` after calling `PipeReader.AdvanceTo` may result in memory corruption (use after free). -* Failing to call `PipeReader.Complete/CompleteAsync` may result in a memory leak. +* Passing the wrong values to `consumed` or `examined` might result in an infinite loop. For example, `PipeReader.AdvanceTo(buffer.Start)` if `buffer.Start` hasn't changed causes the next call to to return immediately before new data arrives. +* Passing the wrong values to `consumed` or `examined` might result in infinite buffering (eventual OOM). +* Using after calling might result in memory corruption (use after free). +* Failing to call / might result in a memory leak. * Checking and exiting the reading logic before processing the buffer results in data loss. The loop exit condition should be based on `ReadResult.Buffer.IsEmpty` and `ReadResult.IsCompleted`. Doing this incorrectly could result in an infinite loop. #### Problematic code ❌ **Data loss** -The `ReadResult` can return the final segment of data when `IsCompleted` is set to `true`. Not reading that data before exiting the read loop will result in data loss. +The `ReadResult` can return the final segment of data when `IsCompleted` is set to `true`. Not reading that data before exiting the read loop results in data loss. [!INCLUDE [pipelines-do-not-use-1](../../../includes/pipelines-do-not-use-1.md)] @@ -245,7 +244,7 @@ The `ReadResult` can return the final segment of data when `IsCompleted` is set ❌ **Infinite loop** -The following logic may result in an infinite loop if the `Result.IsCompleted` is `true` but there's never a complete message in the buffer. +The following logic might result in an infinite loop if the `Result.IsCompleted` is `true` but there's never a complete message in the buffer. [!INCLUDE [pipelines-do-not-use-1](../../../includes/pipelines-do-not-use-1.md)] @@ -253,7 +252,7 @@ The following logic may result in an infinite loop if the `Result.IsCompleted` i [!INCLUDE [pipelines-do-not-use-2](../../../includes/pipelines-do-not-use-2.md)] -Here's another piece of code with the same problem. It's checking for a non-empty buffer before checking `ReadResult.IsCompleted`. Because it's in an `else if`, it will loop forever if there's never a complete message in the buffer. +Here's another piece of code with the same problem. It's checking for a non-empty buffer before checking `ReadResult.IsCompleted`. Because it's in an `else if`, it loops forever if there's never a complete message in the buffer. [!INCLUDE [pipelines-do-not-use-1](../../../includes/pipelines-do-not-use-1.md)] @@ -263,7 +262,7 @@ Here's another piece of code with the same problem. It's checking for a non-empt ❌ **Unresponsive application** -Unconditionally calling `PipeReader.AdvanceTo` with `buffer.End` in the `examined` position may result in the application becoming unresponsive when parsing a single message. The next call to `PipeReader.AdvanceTo` won't return until: +Unconditionally calling with `buffer.End` in the `examined` position might result in the application becoming unresponsive when parsing a single message. The next call to won't return until: * There's more data written to the pipe. * And the new data wasn't previously examined. @@ -276,10 +275,10 @@ Unconditionally calling `PipeReader.AdvanceTo` with `buffer.End` in the `examine ❌ **Out of Memory (OOM)** -With the following conditions, the following code keeps buffering until an occurs: +With the following conditions, this code keeps buffering until an occurs: * There's no maximum message size. -* The data returned from the `PipeReader` doesn't make a complete message. For example, it doesn't make a complete message because the other side is writing a large message (For example, a 4-GB message). +* The data returned from the `PipeReader` doesn't make a complete message. For example, the other side is writing a large message (for example, a 4-GB message). [!INCLUDE [pipelines-do-not-use-1](../../../includes/pipelines-do-not-use-1.md)] @@ -289,7 +288,7 @@ With the following conditions, the following code keeps buffering until an . The following example returns memory that the `Pipe` has discarded and might reuse it for the next operation (read/write). [!INCLUDE [pipelines-do-not-use-1](../../../includes/pipelines-do-not-use-1.md)] @@ -301,7 +300,7 @@ When writing helpers that read the buffer, any returned payload should be copied ## PipeWriter -The manages buffers for writing on the caller's behalf. `PipeWriter` implements [`IBufferWriter`](xref:System.Buffers.IBufferWriter`1). `IBufferWriter` makes it possible to get access to buffers to perform writes without extra buffer copies. +The manages buffers for writing on the caller's behalf. `PipeWriter` implements [`IBufferWriter`](xref:System.Buffers.IBufferWriter`1). `IBufferWriter` provides access to buffers to perform writes without extra buffer copies. :::code language="csharp" source="snippets/pipelines_1/MyPipeWriter.cs" id="snippet"::: @@ -312,44 +311,42 @@ The previous code: * Calls to indicate how many bytes were written to the buffer. * Flushes the `PipeWriter`, which sends the bytes to the underlying device. -The previous method of writing uses the buffers provided by the `PipeWriter`. It could also have used , which: +The previous method of writing uses the buffers provided by the `PipeWriter`. It also could use , which: * Copies the existing buffer to the `PipeWriter`. -* Calls `GetSpan`, `Advance` as appropriate and calls . +* Calls , as appropriate, and calls . :::code language="csharp" source="snippets/pipelines_1/MyPipeWriter.cs" id="snippet2"::: ### Cancellation - supports passing a . Passing a `CancellationToken` results in an `OperationCanceledException` if the token is canceled while there's a flush pending. `PipeWriter.FlushAsync` supports a way to cancel the current flush operation via without raising an exception. Calling `PipeWriter.CancelPendingFlush` causes the current or next call to `PipeWriter.FlushAsync` or `PipeWriter.WriteAsync` to return a with `IsCanceled` set to `true`. This can be useful for halting the yielding flush in a non-destructive and non-exceptional way. - - + supports passing a . Passing a `CancellationToken` results in an `OperationCanceledException` if the token is canceled while there's a flush pending. supports a way to cancel the current flush operation via without raising an exception. Calling `PipeWriter.CancelPendingFlush` causes the current or next call to or `PipeWriter.WriteAsync` to return a with `IsCanceled` set to `true`. This is useful for halting the yielding flush in a non-destructive and non-exceptional way. ### PipeWriter common problems * and return a buffer with at least the requested amount of memory. **Don't** assume exact buffer sizes. -* There's no guarantee that successive calls will return the same buffer or the same-sized buffer. +* Successive calls aren't guaranteed to return the same buffer or the same-sized buffer. * A new buffer must be requested after calling to continue writing more data. The previously acquired buffer can't be written to. -* Calling `GetMemory` or `GetSpan` while there's an incomplete call to `FlushAsync` isn't safe. -* Calling `Complete` or `CompleteAsync` while there's unflushed data can result in memory corruption. +* Calling or while there's an incomplete call to isn't safe. +* Calling or while there's unflushed data might result in memory corruption. -## Tips for using PipeReader and PipeWriter +## Tips for PipeReader and PipeWriter -The following tips will help you use the classes successfully: +Use these tips to successfully use the classes: * Always complete the [PipeReader](xref:System.IO.Pipelines.PipeReader.Complete*?displayProperty=nameWithType) and [PipeWriter](xref:System.IO.Pipelines.PipeWriter.Complete*?displayProperty=nameWithType), including an exception where applicable. * Always call after calling . * Periodically `await` while writing, and always check . Abort writing if `IsCompleted` is `true`, as that indicates the reader is completed and no longer cares about what is written. -* Do call after writing something that you want the `PipeReader` to have access to. -* Do not call `FlushAsync` if the reader can't start until `FlushAsync` finishes, as that may cause a deadlock. -* Ensure that only one context "owns" a `PipeReader` or `PipeWriter` or accesses them. These types are not thread-safe. -* Never access a after calling `AdvanceTo` or completing the `PipeReader`. +* Call after writing something that you want the `PipeReader` to have access to. +* Don't call `FlushAsync` if the reader can't start until `FlushAsync` finishes, as that might cause a deadlock. +* Ensure that only one context "owns" a `PipeReader` or `PipeWriter` or accesses them. These types aren't thread-safe. +* Never access a after calling or completing the `PipeReader`. ## IDuplexPipe -The is a contract for types that support both reading and writing. For example, a network connection would be represented by an `IDuplexPipe`. + is a contract for types that support both reading and writing. For example, a network connection is represented by an `IDuplexPipe`. - Unlike `Pipe`, which contains a `PipeReader` and a `PipeWriter`, `IDuplexPipe` represents a single side of a full duplex connection. That means what is written to the `PipeWriter` will not be read from the `PipeReader`. +Unlike `Pipe`, which contains a `PipeReader` and a `PipeWriter`, `IDuplexPipe` represents a single side of a full duplex connection. What you write to the `PipeWriter` won't be read from the `PipeReader`. ## Streams @@ -357,7 +354,7 @@ When reading or writing stream data, you typically read data using a de-serializ ### Stream example -`PipeReader` and `PipeWriter` instances can be created using the static `Create` methods given a object and optional corresponding creation options. +Create `PipeReader` and `PipeWriter` instances using the static `Create` methods given a object and optional corresponding creation options. The allow for control over the creation of the `PipeReader` instance with the following parameters: @@ -373,9 +370,9 @@ The allow for control over th - is the `MemoryPool` used when allocating memory, and defaults to `null`. > [!IMPORTANT] -> When creating `PipeReader` and `PipeWriter` instances using the `Create` methods, you need to consider the `Stream` object lifetime. If you need access to the stream after the reader or writer is done with it, you'll need to set the `LeaveOpen` flag to `true` on the creation options. Otherwise, the stream will be closed. +> When creating `PipeReader` and `PipeWriter` instances using the `Create` methods, consider the `Stream` object lifetime. If you need access to the stream after the reader or writer is done with it, set the `LeaveOpen` flag to `true` on the creation options. Otherwise, the stream is closed. -The following code demonstrates the creation of `PipeReader` and `PipeWriter` instances using the `Create` methods from a stream. +This code demonstrates creating `PipeReader` and `PipeWriter` instances using the `Create` methods from a stream. :::code language="csharp" source="snippets/pipelines_2/Program.cs"::: diff --git a/includes/pipelines-do-not-use-1.md b/includes/pipelines-do-not-use-1.md index 48881ed4e244d..d3a5072616193 100644 --- a/includes/pipelines-do-not-use-1.md +++ b/includes/pipelines-do-not-use-1.md @@ -1,2 +1,2 @@ > [!WARNING] -> Do **NOT** use the following code. Using this sample will result in data loss, hangs, security issues and should **NOT** be copied. The following sample is provided to explain [PipeReader Common problems](#gotchas). +> Do **NOT** use the following code. Using this sample will result in data loss, hangs, security issues and should **NOT** be copied. The following sample is provided to explain [PipeReader common problems](#pipereader-common-problems). diff --git a/includes/pipelines-do-not-use-2.md b/includes/pipelines-do-not-use-2.md index f5c96d1bd654e..b573ba0e3de2c 100644 --- a/includes/pipelines-do-not-use-2.md +++ b/includes/pipelines-do-not-use-2.md @@ -1,2 +1,2 @@ > [!WARNING] -> Do **NOT** use the preceding code. Using this sample will result in data loss, hangs, security issues and should **NOT** be copied. The preceding sample is provided to explain [PipeReader Common problems](#gotchas). +> Do **NOT** use the preceding code. Using this sample will result in data loss, hangs, security issues and should **NOT** be copied. The preceding sample is provided to explain [PipeReader common problems](#pipereader-common-problems). diff --git a/samples/snippets/fsharp/getting-started/hello.fsx b/samples/snippets/fsharp/getting-started/hello.fsx new file mode 100644 index 0000000000000..b53a16e0c4f19 --- /dev/null +++ b/samples/snippets/fsharp/getting-started/hello.fsx @@ -0,0 +1,7 @@ +printfn "Hello from F# Interactive!" + +let square x = x * x + +[ 1 .. 10 ] +|> List.map square +|> printfn "Squares: %A"