Merge pull request #41528 from dotnet/main

Merge main into live

docs/ai/conceptual/agents.md

@@ -32,7 +32,7 @@ Each agent has three core building blocks: a persona, plugins, and planners.
 
 ### Personas
 
-An agent's persona is its identity: any plugins and planners that the agent uses are tools, but the persona determines how it uses those tools. You use [instructions](prompt-engineering-dotnet.md#use-instructions-to-tell-the-model-what-to-do) in a prompt to establish an agent's persona.
+An agent's persona is its identity: any plugins and planners that the agent uses are tools, but the persona determines how it uses those tools. You use [instructions](prompt-engineering-dotnet.md#use-instructions-to-improve-the-completion) in a prompt to establish an agent's persona.
 
 For example, you can use instructions to tell an agent that it is helping people manage emails, and to explain its decisions as it makes them. Your prompt might look something like this:
 

docs/ai/conceptual/rag.md

@@ -30,7 +30,7 @@ To perform RAG, you must process each data source that you want to use for retri
 1. Store the converted data in a location that allows efficient access. Additionally, it's important to store relevant metadata for citations or references when the LLM provides responses.
 1. Feed your converted data to LLMs in prompts.
 
-:::image type="content" source="../media/rag/architecture.png" alt-text="Screenshot of a diagram of the technical overview of an LLM walking through rag steps.":::
+:::image type="content" source="../media/rag/architecture.png" alt-text="Screenshot of a diagram of the technical overview of an LLM walking through RAG steps.":::
 
 - **Source data**: This is where your data exists. It could be a file/folder on your machine, a file in cloud storage, an Azure Machine Learning data asset, a Git repository, or an SQL database.
 - **Data chunking**: The data in your source needs to be converted to plain text. For example, word documents or PDFs need to be cracked open and converted to text. The text is then chunked into smaller pieces.

docs/ai/conceptual/understanding-openai-functions.md

@@ -2,7 +2,7 @@
 title: "Understanding OpenAI Function Calling"
 description: "Understand how function calling enables you to integrate external tools with your OpenAI application."
 author: haywoodsloan
-ms.topic: concept-article 
+ms.topic: concept-article
 ms.date: 05/14/2024
 
 #customer intent: As a .NET developer, I want to understand OpenAI function calling so that I can integrate external tools with AI completions in my .NET project.
@@ -11,7 +11,7 @@ ms.date: 05/14/2024
 
 # Understand OpenAI function calling
 
-Function calling is an OpenAI model feature that lets you describe functions and their arguments in prompts using JSON. Instead of invoking the function itself, the model returns a JSON output describing what functions should be called and the arguments to use.
+*Function calling* is an OpenAI model feature that lets you describe functions and their arguments in prompts using JSON. Instead of invoking the function itself, the model returns a JSON output describing what functions should be called and the arguments to use.
 
 Function calling simplifies how you connect external tools to your AI model. First, you specify each tool's functions to the model. Then the model decides which functions should be called, based on the prompt question. The model uses the function call results to build a more accurate and consistent response.
 

docs/ai/conceptual/understanding-tokens.md

@@ -9,7 +9,7 @@ ms.date: 05/14/2024
 
 ---
 
-# Understanding tokens
+# Understand tokens
 
 Tokens are words, character sets, or combinations of words and punctuation that are used by large language models (LLMs) to decompose text into. Tokenization is the first step in training. The LLM analyzes the semantic relationships between tokens, such as how commonly they're used together or whether they're used in similar contexts. After training, the LLM uses those patterns and relationships to generate a sequence of output tokens based on the input sequence.
 

docs/csharp/fundamentals/coding-style/coding-conventions.md

@@ -9,7 +9,7 @@ helpviewer_keyword:
 ---
 # Common C# code conventions
 
-A code standard is essential for maintaining code readability, consistency, and collaboration within a development team. Code that follows industry practices and established guidelines is easier to understand, maintain, and extend. Most projects enforce a consistent style through code conventions. The [`dotnet/docs`](https://github.com/dotnet/docs) and [`dotnet/samples`](https://github.com/dotnet/samples) projects are no exception. In this series of articles, you learn our coding conventions and the tools we use to enforce them. You can take our conventions as-is, or modify them to suit your team's needs.
+Coding conventions are essential for maintaining code readability, consistency, and collaboration within a development team. Code that follows industry practices and established guidelines is easier to understand, maintain, and extend. Most projects enforce a consistent style through code conventions. The [`dotnet/docs`](https://github.com/dotnet/docs) and [`dotnet/samples`](https://github.com/dotnet/samples) projects are no exception. In this series of articles, you learn our coding conventions and the tools we use to enforce them. You can take our conventions as-is, or modify them to suit your team's needs.
 
 We chose our conventions based on the following goals:
 
@@ -27,9 +27,9 @@ This article explains our guidelines. The guidelines have evolved over time, and
 
 ## Tools and analyzers
 
-Tools can help your team enforce your standards. You can enable [code analysis](../../../fundamentals/code-analysis/overview.md) to enforce the rules you prefer. You can also create an [editorconfig](/visualstudio/ide/create-portable-custom-editor-options) so that Visual Studio automatically enforces your style guidelines. As a starting point, you can copy the [dotnet/docs repo's file](https://github.com/dotnet/docs/blob/main/.editorconfig) to use our style.
+Tools can help your team enforce your conventions. You can enable [code analysis](../../../fundamentals/code-analysis/overview.md) to enforce the rules you prefer. You can also create an [editorconfig](/visualstudio/ide/create-portable-custom-editor-options) so that Visual Studio automatically enforces your style guidelines. As a starting point, you can copy the [dotnet/docs repo's file](https://github.com/dotnet/docs/blob/main/.editorconfig) to use our style.
 
-These tools make it easier for your team to adopt your preferred guidelines. Visual Studio applies the rules in all `.editorconfig` files in scope to format your code. You can use multiple configurations to enforce corporate-wide standards, team standards, and even granular project standards.
+These tools make it easier for your team to adopt your preferred guidelines. Visual Studio applies the rules in all `.editorconfig` files in scope to format your code. You can use multiple configurations to enforce corporate-wide conventions, team conventions, and even granular project conventions.
 
 Code analysis produces warnings and diagnostics when the enabled rules are violated. You configure the rules you want applied to your project. Then, each CI build notifies developers when they violate any of the rules.
 

docs/csharp/fundamentals/program-structure/main-command-line.md

@@ -14,7 +14,7 @@ helpviewer_keywords:
 ---
 # Main() and command-line arguments
 
-The `Main` method is the entry point of a C# application. (Libraries and services do not require a `Main` method as an entry point.) When the application is started, the `Main` method is the first method that is invoked.
+The `Main` method is the entry point of a C# application. When the application is started, the `Main` method is the first method that is invoked.
 
 There can only be one entry point in a C# program. If you have more than one class that has a `Main` method, you must compile your program with the **StartupObject** compiler option to specify which `Main` method to use as the entry point. For more information, see [**StartupObject** (C# Compiler Options)](../../language-reference/compiler-options/advanced.md#mainentrypoint-or-startupobject).
 
@@ -29,47 +29,50 @@ For more information, see [Top-level statements](top-level-statements.md).
 ## Overview
 
 - The `Main` method is the entry point of an executable program; it is where the program control starts and ends.
-- `Main` is declared inside a class or struct. `Main` must be [`static`](../../language-reference/keywords/static.md) and it need not be [`public`](../../language-reference/keywords/public.md). (In the earlier example, it receives the default access of [`private`](../../language-reference/keywords/private.md).) An enclosing `class` can be `static`.
+- `Main` must be declared inside a class or struct. The enclosing `class` can be `static`.
+- `Main` must be [`static`](../../language-reference/keywords/static.md).
+- `Main` can have any [access modifier](../../programming-guide/classes-and-structs/access-modifiers.md) (except `file`).
 - `Main` can either have a `void`, `int`, `Task`, or `Task<int>` return type.
 - If and only if `Main` returns a `Task` or `Task<int>`, the declaration of `Main` may include the [`async`](../../language-reference/keywords/async.md) modifier. This specifically excludes an `async void Main` method.
 - The `Main` method can be declared with or without a `string[]` parameter that contains command-line arguments. When using Visual Studio to create Windows applications, you can add the parameter manually or else use the <xref:System.Environment.GetCommandLineArgs> method to obtain the command-line arguments. Parameters are read as zero-indexed command-line arguments. Unlike C and C++, the name of the program is not treated as the first command-line argument in the `args` array, but it is the first element of the <xref:System.Environment.GetCommandLineArgs> method.
 
-The following list shows valid `Main` signatures:
+The following list shows the most common `Main` declarations:
 
 ```csharp
-public static void Main() { }
-public static int Main() { }
-public static void Main(string[] args) { }
-public static int Main(string[] args) { }
-public static async Task Main() { }
-public static async Task<int> Main() { }
-public static async Task Main(string[] args) { }
-public static async Task<int> Main(string[] args) { }
+static void Main() { }
+static int Main() { }
+static void Main(string[] args) { }
+static int Main(string[] args) { }
+static async Task Main() { }
+static async Task<int> Main() { }
+static async Task Main(string[] args) { }
+static async Task<int> Main(string[] args) { }
 ```
 
-The preceding examples all use the `public` accessor modifier. That's typical, but not required.
+The preceding examples don't specify an access modifier, so they're implicitly `private` by default. That's typical, but it's possible to specify any explicit access modifier.
 
-The addition of `async` and `Task`, `Task<int>` return types simplifies program code when console applications need to start and `await` asynchronous operations in `Main`.
+> [!TIP]
+> The addition of `async` and `Task`, `Task<int>` return types simplifies program code when console applications need to start and `await` asynchronous operations in `Main`.
 
 ## Main() return values
 
 You can return an `int` from the `Main` method by defining the method in one of the following ways:
 
-| `Main` method code             | `Main` signature                             |
-|--------------------------------|----------------------------------------------|
-| No use of `args` or `await`    | `static int Main()`                          |
-| Uses `args`, no use of `await` | `static int Main(string[] args)`             |
-| No use of `args`, uses `await` | `static async Task<int> Main()`              |
-| Uses `args` and `await`        | `static async Task<int> Main(string[] args)` |
+| `Main` declaration                           | `Main` method code             |
+|----------------------------------------------|--------------------------------|
+| `static int Main()`                          | No use of `args` or `await`    |
+| `static int Main(string[] args)`             | Uses `args`, no use of `await` |
+| `static async Task<int> Main()`              | No use of `args`, uses `await` |
+| `static async Task<int> Main(string[] args)` | Uses `args` and `await`        |
 
 If the return value from `Main` is not used, returning `void` or `Task` allows for slightly simpler code.
 
-| `Main` method code             | `Main` signature                        |
-|--------------------------------|-----------------------------------------|
-| No use of `args` or `await`    | `static void Main()`                    |
-| Uses `args`, no use of `await` | `static void Main(string[] args)`       |
-| No use of `args`, uses `await` | `static async Task Main()`              |
-| Uses `args` and `await`        | `static async Task Main(string[] args)` |
+| `Main` declaration                      | `Main` method code             |
+|-----------------------------------------|--------------------------------|
+| `static void Main()`                    | No use of `args` or `await`    |
+| `static void Main(string[] args)`       | Uses `args`, no use of `await` |
+| `static async Task Main()`              | No use of `args`, uses `await` |
+| `static async Task Main(string[] args)` | Uses `args` and `await`        |
 
 However, returning `int` or `Task<int>` enables the program to communicate status information to other programs or scripts that invoke the executable file.
 
@@ -112,9 +115,9 @@ When you declare an `async` return value for `Main`, the compiler generates the
 ```csharp
 class AsyncMainReturnValTest
 {
-    public static void Main()
+    public static int Main()
     {
-        AsyncConsoleWork().GetAwaiter().GetResult();
+        return AsyncConsoleWork().GetAwaiter().GetResult();
     }
 
     private static async Task<int> AsyncConsoleWork()
@@ -145,24 +148,24 @@ When the application entry point returns a `Task` or `Task<int>`, the compiler g
 
 You can send arguments to the `Main` method by defining the method in one of the following ways:
 
-| `Main` method code                 | `Main` signature                             |
-|------------------------------------|----------------------------------------------|
-| No return value, no use of `await` | `static void Main(string[] args)`            |
-| Return value, no use of `await`    | `static int Main(string[] args)`             |
-| No return value, uses `await`      | `static async Task Main(string[] args)`      |
-| Return value, uses `await`         | `static async Task<int> Main(string[] args)` |
+| `Main` declaration                           | `Main` method code                 |
+|----------------------------------------------|------------------------------------|
+| `static void Main(string[] args)`            | No return value, no use of `await` |
+| `static int Main(string[] args)`             | Return value, no use of `await`    |
+| `static async Task Main(string[] args)`      | No return value, uses `await`      |
+| `static async Task<int> Main(string[] args)` | Return value, uses `await`         |
 
-If the arguments are not used, you can omit `args` from the method signature for slightly simpler code:
+If the arguments are not used, you can omit `args` from the method declaration for slightly simpler code:
 
-| `Main` method code                 | `Main` signature                |
-|------------------------------------|---------------------------------|
-| No return value, no use of `await` | `static void Main()`            |
-| Return value, no use of `await`    | `static int Main()`             |
-| No return value, uses `await`      | `static async Task Main()`      |
-| Return value, uses `await`         | `static async Task<int> Main()` |
+| `Main` declaration              | `Main` method code                 |
+|---------------------------------|------------------------------------|
+| `static void Main()`            | No return value, no use of `await` |
+| `static int Main()`             | Return value, no use of `await`    |
+| `static async Task Main()`      | No return value, uses `await`      |
+| `static async Task<int> Main()` | Return value, uses `await`         |
 
 > [!NOTE]
-> You can also use <xref:System.Environment.CommandLine%2A?displayProperty=nameWithType> or <xref:System.Environment.GetCommandLineArgs%2A?displayProperty=nameWithType> to access the command-line arguments from any point in a console or Windows Forms application. To enable command-line arguments in the `Main` method signature in a Windows Forms application, you must manually modify the signature of `Main`. The code generated by the Windows Forms designer creates `Main` without an input parameter.
+> You can also use <xref:System.Environment.CommandLine%2A?displayProperty=nameWithType> or <xref:System.Environment.GetCommandLineArgs%2A?displayProperty=nameWithType> to access the command-line arguments from any point in a console or Windows Forms application. To enable command-line arguments in the `Main` method declaration in a Windows Forms application, you must manually modify the declaration of `Main`. The code generated by the Windows Forms designer creates `Main` without an input parameter.
 
 The parameter of the `Main` method is a <xref:System.String> array that represents the command-line arguments. Usually you determine whether arguments exist by testing the `Length` property, for example: