diff --git a/.github/prompts/error-consolidation.md b/.github/prompts/error-consolidation.md index aa1d4db2f7c56..6fc5e79dfadd6 100644 --- a/.github/prompts/error-consolidation.md +++ b/.github/prompts/error-consolidation.md @@ -68,7 +68,7 @@ Rework the highlighted section so the focus is on how to correct each error. Thi ## Verify error messages -For every line in this table, 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: +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. diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 96e2cbcc25c90..cfa21e966a081 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -475,7 +475,7 @@ | Common | NuGet [2.2.1](https://www.nuget.org/packages/Microsoft.Azure.Common/2.2.1) | | | | Common - Dependencies | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Common.Dependencies/1.0.0) | | | | Computer Vision | NuGet [7.0.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.ComputerVision/7.0.1) | | GitHub [7.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.ComputerVision_6.0.0-preview.1/sdk/cognitiveservices/Vision.ComputerVision) | -| Cosmos DB | NuGet [3.47.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.47.0)
NuGet [3.56.0-preview.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.56.0-preview.0) | [docs](/dotnet/api/overview/azure/cosmosdb) | GitHub [3.47.0](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/3.12.0/Microsoft.Azure.Cosmos) | +| Cosmos DB | NuGet [3.47.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.47.0)
NuGet [3.57.0-preview.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.57.0-preview.0) | [docs](/dotnet/api/overview/azure/cosmosdb) | GitHub [3.47.0](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/3.12.0/Microsoft.Azure.Cosmos) | | Custom Vision Prediction | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction/2.0.0) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction_2.0.0/sdk/cognitiveservices/Vision.CustomVision.Prediction) | | Custom Vision Training | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training/2.0.0)
NuGet [2.1.0-preview](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training/2.1.0-preview) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training_2.0.0/sdk/cognitiveservices/Vision.CustomVision.Training) | | Data Lake Analytics | NuGet [1.4.211011](https://www.nuget.org/packages/Microsoft.Azure.DataLake.USQL.SDK/1.4.211011) | | | diff --git a/docs/azure/sdk/authentication/local-development-dev-accounts.md b/docs/azure/sdk/authentication/local-development-dev-accounts.md index b6504fcb876a2..ab5e13c3865dd 100644 --- a/docs/azure/sdk/authentication/local-development-dev-accounts.md +++ b/docs/azure/sdk/authentication/local-development-dev-accounts.md @@ -2,7 +2,7 @@ title: Authenticate .NET apps to Azure using developer accounts description: Learn how to authenticate your application to Azure services when using the Azure SDK for .NET during local development using developer accounts. ms.topic: how-to -ms.date: 03/14/2025 +ms.date: 11/25/2025 ms.custom: - devx-track-dotnet - engagement-fy23 @@ -122,4 +122,36 @@ Connect-AzAccount -UseDeviceAuthentication --- -[!INCLUDE [Implement DefaultAzureCredential](<../includes/implement-defaultazurecredential.md>)] +## Authenticate to Azure services from your app + +The [Azure Identity library](/dotnet/api/azure.identity?view=azure-dotnet&preserve-view=true) provides implementations of that support various scenarios and Microsoft Entra authentication flows. The steps ahead demonstrate how to use or a specific development tool credential when working with user accounts locally. + +### Implement the code + +Complete the following steps: + +1. Add references to the [Azure.Identity](https://www.nuget.org/packages/Azure.Identity) and the [Microsoft.Extensions.Azure](https://www.nuget.org/packages/Microsoft.Extensions.Azure) packages in your project: + + ```dotnetcli + dotnet add package Azure.Identity + dotnet add package Microsoft.Extensions.Azure + ``` + +1. In `Program.cs`, add `using` directives for the `Azure.Identity` and `Microsoft.Extensions.Azure` namespaces. + +1. Register the Azure service client using the corresponding `Add`-prefixed extension method. + + Azure services are accessed using specialized client classes from the Azure SDK client libraries. Register these client types so you can access them through dependency injection across your app. + +1. Pass a `TokenCredential` instance to the `UseCredential` method. Common `TokenCredential` examples include: + + - A `DefaultAzureCredential` instance optimized for local development. This example sets environment variable `AZURE_TOKEN_CREDENTIALS` to `dev`. For more information, see [Exclude a credential type category](credential-chains.md#exclude-a-credential-type-category). + + :::code language="csharp" source="../snippets/authentication/local-dev-account/Program.cs" id="snippet_DefaultAzureCredentialDev"::: + + - An instance of a credential corresponding to a specific development tool, such as `VisualStudioCredential`. + + :::code language="csharp" source="../snippets/authentication/local-dev-account/Program.cs" id="snippet_VisualStudioCredential"::: + + > [!TIP] + > When your team uses multiple development tools to authenticate with Azure, prefer a local development-optimized instance of `DefaultAzureCredential` over tool-specific credentials. diff --git a/docs/azure/sdk/includes/implement-defaultazurecredential.md b/docs/azure/sdk/includes/implement-defaultazurecredential.md deleted file mode 100644 index c0c83166e1e2e..0000000000000 --- a/docs/azure/sdk/includes/implement-defaultazurecredential.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -ms.topic: include -ms.date: 04/25/2025 ---- - -## Authenticate to Azure services from your app - -The [Azure Identity library](/dotnet/api/azure.identity?view=azure-dotnet&preserve-view=true) provides various *credentials*—implementations of `TokenCredential` adapted to supporting different scenarios and Microsoft Entra authentication flows. The steps ahead demonstrate how to use when working with user accounts locally. - -### Implement the code - -[DefaultAzureCredential](../authentication/credential-chains.md#defaultazurecredential-overview) is an opinionated, ordered sequence of mechanisms for authenticating to Microsoft Entra ID. Each authentication mechanism is a class derived from the [TokenCredential](/dotnet/api/azure.core.tokencredential?view=azure-dotnet&preserve-view=true) class and is known as a *credential*. At runtime, `DefaultAzureCredential` attempts to authenticate using the first credential. If that credential fails to acquire an access token, the next credential in the sequence is attempted, and so on, until an access token is successfully obtained. In this way, your app can use different credentials in different environments without writing environment-specific code. - -To use `DefaultAzureCredential`, add the [Azure.Identity](/dotnet/api/azure.identity) and optionally the [Microsoft.Extensions.Azure](/dotnet/api/microsoft.extensions.azure) packages to your application: - -### [Command Line](#tab/command-line) - -In a terminal of your choice, navigate to the application project directory and run the following commands: - -```dotnetcli -dotnet add package Azure.Identity -dotnet add package Microsoft.Extensions.Azure -``` - -### [NuGet Package Manager](#tab/nuget-package) - -Right-click your project in Visual Studio's **Solution Explorer** window and select **Manage NuGet Packages**. Search for **Azure.Identity**, and install the matching package. Repeat this process for the **Microsoft.Extensions.Azure** package. - -:::image type="content" source="../media/nuget-azure-identity.png" alt-text="Install a package using the package manager."::: - ---- - -Azure services are accessed using specialized client classes from the various Azure SDK client libraries. These classes and your own custom services should be registered so they can be accessed via dependency injection throughout your app. In `Program.cs`, complete the following steps to register a client class and `DefaultAzureCredential`: - -1. Include the `Azure.Identity` and `Microsoft.Extensions.Azure` namespaces via `using` directives. -1. Register the Azure service client using the corresponding `Add`-prefixed extension method. -1. Pass an instance of `DefaultAzureCredential` to the `UseCredential` method. - -:::code language="csharp" source="../snippets/authentication/local-dev-account/Program.cs" id="snippet_DefaultAzureCredential_UseCredential"::: - -An alternative to the `UseCredential` method is to provide the credential to the service client directly: - -:::code language="csharp" source="../snippets/authentication/local-dev-account/Program.cs" id="snippet_DefaultAzureCredential"::: diff --git a/docs/azure/sdk/snippets/authentication/Directory.Packages.props b/docs/azure/sdk/snippets/authentication/Directory.Packages.props index 4508202931eed..70840c23b7184 100644 --- a/docs/azure/sdk/snippets/authentication/Directory.Packages.props +++ b/docs/azure/sdk/snippets/authentication/Directory.Packages.props @@ -7,9 +7,9 @@ - - - + + + diff --git a/docs/azure/sdk/snippets/authentication/local-dev-account/UserAssignedIdentityClientId.csproj b/docs/azure/sdk/snippets/authentication/local-dev-account/LocalDevAccount.csproj similarity index 91% rename from docs/azure/sdk/snippets/authentication/local-dev-account/UserAssignedIdentityClientId.csproj rename to docs/azure/sdk/snippets/authentication/local-dev-account/LocalDevAccount.csproj index 94c4ea943ef74..4c193bf82cfaf 100644 --- a/docs/azure/sdk/snippets/authentication/local-dev-account/UserAssignedIdentityClientId.csproj +++ b/docs/azure/sdk/snippets/authentication/local-dev-account/LocalDevAccount.csproj @@ -1,7 +1,7 @@ - net9.0 + net10.0 enable enable diff --git a/docs/azure/sdk/snippets/authentication/local-dev-account/Program.cs b/docs/azure/sdk/snippets/authentication/local-dev-account/Program.cs index 715e0ec60b865..23984418924d1 100644 --- a/docs/azure/sdk/snippets/authentication/local-dev-account/Program.cs +++ b/docs/azure/sdk/snippets/authentication/local-dev-account/Program.cs @@ -1,11 +1,10 @@ -using Azure.Identity; -using Microsoft.Extensions.Azure; +using Microsoft.Extensions.Azure; using Azure.Storage.Blobs; -using Azure.Core; +using Azure.Identity; var builder = WebApplication.CreateBuilder(args); -registerUsingServicePrincipal(builder); +registerUsingUserPrincipal(builder); var app = builder.Build(); @@ -43,22 +42,30 @@ app.Run(); -void registerUsingServicePrincipal(WebApplicationBuilder builder) +void registerUsingUserPrincipal(WebApplicationBuilder builder) { - #region snippet_DefaultAzureCredential_UseCredential + #region snippet_VisualStudioCredential builder.Services.AddAzureClients(clientBuilder => { clientBuilder.AddBlobServiceClient( new Uri("https://.blob.core.windows.net")); + + VisualStudioCredential credential = new(); + clientBuilder.UseCredential(credential); }); - #endregion snippet_DefaultAzureCredential_UseCredential + #endregion snippet_VisualStudioCredential - #region snippet_DefaultAzureCredential - builder.Services.AddSingleton(_ => - new BlobServiceClient( - new Uri("https://.blob.core.windows.net"), - new DefaultAzureCredential())); - #endregion snippet_DefaultAzureCredential + #region snippet_DefaultAzureCredentialDev + builder.Services.AddAzureClients(clientBuilder => + { + clientBuilder.AddBlobServiceClient( + new Uri("https://.blob.core.windows.net")); + + DefaultAzureCredential credential = new( + DefaultAzureCredential.DefaultEnvironmentVariableName); + clientBuilder.UseCredential(credential); + }); + #endregion snippet_DefaultAzureCredentialDev } internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary) diff --git a/docs/core/tools/dotnet-project-convert.md b/docs/core/tools/dotnet-project-convert.md new file mode 100644 index 0000000000000..65ce1d147e93d --- /dev/null +++ b/docs/core/tools/dotnet-project-convert.md @@ -0,0 +1,138 @@ +--- +title: dotnet project convert command +description: The 'dotnet project convert' command converts a file-based program to a project-based program. +ms.date: 10/25/2025 +ai-usage: ai-assisted +--- +# dotnet project convert + +**This article applies to:** ✔️ .NET 10 SDK and later versions + +## Name + +`dotnet project convert` - Converts a file-based program to a project-based program. + +## Synopsis + +```dotnetcli +dotnet project convert [--dry-run] [--force] [--interactive] + [-o|--output ] + +dotnet project convert -h|--help +``` + +## Description + +The `dotnet project convert` command converts a file-based program to a project-based program. This command creates a new directory named for your file, scaffolds a *.csproj* file, moves your code into a file with the same name as the input file, and translates any `#:` directives into MSBuild properties and references. + +This makes the transition seamless, from a single file to a fully functional, buildable, and extensible project. When your file-based app grows in complexity, or you simply want the extra capabilities afforded in project-based apps, you can convert it to a standard project. + +### Conversion process + +The command performs the following operations: + +1. Creates a new directory named after the input file (without extension). +2. Generates a *.csproj* file with appropriate SDK and properties. +3. Moves the source code to a file with the same name as the input file. +4. Removes `#:` directives from the source code. +5. Translates `#:sdk` directives: the first `#:sdk` directive becomes the `` or `` attribute, and any additional `#:sdk` directives become `` or `` elements. +6. Translates `#:package` directives to `` elements in the project file. +7. Translates `#:property` directives to MSBuild properties in the project file. +8. Sets appropriate MSBuild properties based on the SDK and framework detected. + +## Arguments + +- `FILE` + + The path to the file-based program to convert. The file must be a C# source file (typically with a *.cs* extension). + +## Options + +- **`--dry-run`** + + Determines changes without actually modifying the file system. Shows what would be created or modified without performing the conversion. + +- **`--force`** + + Forces conversion even if there are malformed directives. By default, the command fails if it encounters directives that cannot be properly parsed or converted. + +- [!INCLUDE [interactive](../../../includes/cli-interactive.md)] + +- **`-o|--output `** + + Specifies the output directory for the converted project. If not specified, a directory is created with the same name as the input file (without extension) in the current directory. + +- [!INCLUDE [help](../../../includes/cli-help.md)] + +## Examples + +- Convert a file-based program to a project: + + ```dotnetcli + dotnet project convert app.cs + ``` + + Given a folder containing *app.cs* with the following content: + + ```csharp + #:sdk Microsoft.NET.Sdk.Web + #:package Microsoft.AspNetCore.OpenApi@10.*-* + + var builder = WebApplication.CreateBuilder(); + + builder.Services.AddOpenApi(); + + var app = builder.Build(); + + app.MapGet("/", () => "Hello, world!"); + app.Run(); + ``` + + Running `dotnet project convert app.cs` results in a folder called *app* containing: + + *app/app.cs*: + + ```csharp + var builder = WebApplication.CreateBuilder(); + + builder.Services.AddOpenApi(); + + var app = builder.Build(); + + app.MapGet("/", () => "Hello, world!"); + app.Run(); + ``` + + *app/app.csproj*: + + ```xml + + + + Exe + net10.0 + enable + enable + true + true + + + + + + + + ``` + +- Convert a file-based program to a project in a specific output directory: + + ```dotnetcli + dotnet project convert app.cs --output MyProject + ``` + +## See also + +- [dotnet build](dotnet-build.md) +- [dotnet run](dotnet-run.md) +- [dotnet publish](dotnet-publish.md) +- [Tutorial: Build file-based C# programs](../../csharp/fundamentals/tutorials/file-based-programs.md) diff --git a/docs/core/tools/index.md b/docs/core/tools/index.md index fb36452000943..2efd06ea1603f 100644 --- a/docs/core/tools/index.md +++ b/docs/core/tools/index.md @@ -79,6 +79,7 @@ The following commands are installed by default: - [`package remove`](dotnet-package-remove.md) - [`package search`](dotnet-package-search.md) - [`package update`](dotnet-package-update.md) +- [`project convert`](dotnet-project-convert.md) (Available since .NET 10 SDK) - [`reference add`](dotnet-reference-add.md) - [`reference list`](dotnet-reference-list.md) - [`reference remove`](dotnet-reference-remove.md) diff --git a/docs/csharp/advanced-topics/interface-implementation/mixins-with-default-interface-methods.md b/docs/csharp/advanced-topics/interface-implementation/mixins-with-default-interface-methods.md index e420e3dc527e4..3a93c9ac0c83a 100644 --- a/docs/csharp/advanced-topics/interface-implementation/mixins-with-default-interface-methods.md +++ b/docs/csharp/advanced-topics/interface-implementation/mixins-with-default-interface-methods.md @@ -1,7 +1,7 @@ --- title: Create mixin types using default interface methods description: Using default interface members you can extend interfaces with optional default implementations for implementors. -ms.date: 07/31/2024 +ms.date: 11/24/2025 --- # Tutorial: Mix functionality in when creating classes using interfaces with default interface methods @@ -19,13 +19,13 @@ In this tutorial, you learn how to: You need to set up your machine to run .NET, including the C# compiler. The C# compiler is available with [Visual Studio 2022](https://visualstudio.microsoft.com/downloads), or the [.NET SDK](https://dotnet.microsoft.com/download/dotnet). -## Limitations of extension methods +## Limitations of extensions -One way you can implement behavior that appears as part of an interface is to define [extension methods](../../programming-guide/classes-and-structs/extension-methods.md) that provide the default behavior. Interfaces declare a minimum set of members while providing a greater surface area for any class that implements that interface. For example, the extension methods in provide the implementation for any sequence to be the source of a LINQ query. +One way you can implement behavior that appears as part of an interface is to define [extension members](../../programming-guide/classes-and-structs/extension-methods.md) that provide the default behavior. Interfaces declare a minimum set of members while providing a greater surface area for any class that implements that interface. For example, the extension members in provide the implementation for any sequence to be the source of a LINQ query. -Extension methods are resolved at compile time, using the declared type of the variable. Classes that implement the interface can provide a better implementation for any extension method. Variable declarations must match the implementing type to enable the compiler to choose that implementation. When the compile-time type matches the interface, method calls resolve to the extension method. Another concern with extension methods is that those methods are accessible wherever the class containing the extension methods is accessible. Classes can't declare if they should or shouldn't provide features declared in extension methods. +Extension members are resolved at compile time, using the declared type of the variable. Classes that implement the interface can provide a better implementation for any extension member. Variable declarations must match the implementing type to enable the compiler to choose that implementation. When the compile-time type matches the interface, method calls resolve to the extension member. Another concern with extension members is that those members are accessible wherever the class containing the extension member is accessible. Classes can't declare if they should or shouldn't provide features declared in extension members. -You can declare the default implementations as interface methods. Then, every class automatically uses the default implementation. Any class that can provide a better implementation can override the interface method definition with a better algorithm. In one sense, this technique sounds similar to how you could use [extension methods](../../programming-guide/classes-and-structs/extension-methods.md). +You can declare the default implementations as interface methods. Then, every class automatically uses the default implementation. Any class that can provide a better implementation can override the interface method definition with a better algorithm. In one sense, this technique sounds similar to how you could use [extension members](../../programming-guide/classes-and-structs/extension-methods.md). In this article, you learn how default interface implementations enable new scenarios. @@ -38,7 +38,7 @@ Consider a home automation application. You probably have many different types o Some of these extended capabilities could be emulated in devices that support the minimal set. That indicates providing a default implementation. For those devices that have more capabilities built in, the device software would use the native capabilities. For other lights, they could choose to implement the interface and use the default implementation. -Default interface members provide a better solution for this scenario than extension methods. Class authors can control which interfaces they choose to implement. Those interfaces they choose are available as methods. In addition, because default interface methods are virtual by default, the method dispatch always chooses the implementation in the class. +Default interface members provide a better solution for this scenario than extension members. Class authors can control which interfaces they choose to implement. Those interfaces they choose are available as methods. In addition, because default interface methods are virtual by default, the method dispatch always chooses the implementation in the class. Let's create the code to demonstrate these differences. diff --git a/docs/csharp/advanced-topics/interface-implementation/snippets/mixins-with-default-interface-methods/mixins-with-interfaces.csproj b/docs/csharp/advanced-topics/interface-implementation/snippets/mixins-with-default-interface-methods/mixins-with-interfaces.csproj index 08cdb396f1014..6f6cafcaa7818 100644 --- a/docs/csharp/advanced-topics/interface-implementation/snippets/mixins-with-default-interface-methods/mixins-with-interfaces.csproj +++ b/docs/csharp/advanced-topics/interface-implementation/snippets/mixins-with-default-interface-methods/mixins-with-interfaces.csproj @@ -2,7 +2,7 @@ Exe - net8.0 + net10.0 enable enable mixins_with_interfaces diff --git a/docs/csharp/fundamentals/functional/snippets/deconstructing-tuples/deconstruct-extension1.cs b/docs/csharp/fundamentals/functional/snippets/deconstructing-tuples/deconstruct-extension1.cs index d5b9db924ede5..2ae1b453546fa 100644 --- a/docs/csharp/fundamentals/functional/snippets/deconstructing-tuples/deconstruct-extension1.cs +++ b/docs/csharp/fundamentals/functional/snippets/deconstructing-tuples/deconstruct-extension1.cs @@ -4,84 +4,87 @@ public static class ReflectionExtensions { - public static void Deconstruct(this PropertyInfo p, out bool isStatic, - out bool isReadOnly, out bool isIndexed, - out Type propertyType) + extension(PropertyInfo propertyInfo) { - var getter = p.GetMethod; + public void Deconstruct(out bool isStatic, + out bool isReadOnly, out bool isIndexed, + out Type propertyType) + { + var getter = propertyInfo.GetMethod; - // Is the property read-only? - isReadOnly = ! p.CanWrite; + // Is the property read-only? + isReadOnly = ! propertyInfo.CanWrite; - // Is the property instance or static? - isStatic = getter.IsStatic; + // Is the property instance or static? + isStatic = getter.IsStatic; - // Is the property indexed? - isIndexed = p.GetIndexParameters().Length > 0; + // Is the property indexed? + isIndexed = propertyInfo.GetIndexParameters().Length > 0; - // Get the property type. - propertyType = p.PropertyType; - } + // Get the property type. + propertyType = propertyInfo.PropertyType; + } - public static void Deconstruct(this PropertyInfo p, out bool hasGetAndSet, - out bool sameAccess, out string access, - out string getAccess, out string setAccess) - { - hasGetAndSet = sameAccess = false; - string getAccessTemp = null; - string setAccessTemp = null; + public void Deconstruct(out bool hasGetAndSet, + out bool sameAccess, out string access, + out string getAccess, out string setAccess) + { + hasGetAndSet = sameAccess = false; + string getAccessTemp = null; + string setAccessTemp = null; - MethodInfo getter = null; - if (p.CanRead) - getter = p.GetMethod; + MethodInfo getter = null; + if (propertyInfo.CanRead) + getter = propertyInfo.GetMethod; - MethodInfo setter = null; - if (p.CanWrite) - setter = p.SetMethod; + MethodInfo setter = null; + if (propertyInfo.CanWrite) + setter = propertyInfo.SetMethod; - if (setter != null && getter != null) - hasGetAndSet = true; + if (setter != null && getter != null) + hasGetAndSet = true; - if (getter != null) - { - if (getter.IsPublic) - getAccessTemp = "public"; - else if (getter.IsPrivate) - getAccessTemp = "private"; - else if (getter.IsAssembly) - getAccessTemp = "internal"; - else if (getter.IsFamily) - getAccessTemp = "protected"; - else if (getter.IsFamilyOrAssembly) - getAccessTemp = "protected internal"; - } + if (getter != null) + { + if (getter.IsPublic) + getAccessTemp = "public"; + else if (getter.IsPrivate) + getAccessTemp = "private"; + else if (getter.IsAssembly) + getAccessTemp = "internal"; + else if (getter.IsFamily) + getAccessTemp = "protected"; + else if (getter.IsFamilyOrAssembly) + getAccessTemp = "protected internal"; + } - if (setter != null) - { - if (setter.IsPublic) - setAccessTemp = "public"; - else if (setter.IsPrivate) - setAccessTemp = "private"; - else if (setter.IsAssembly) - setAccessTemp = "internal"; - else if (setter.IsFamily) - setAccessTemp = "protected"; - else if (setter.IsFamilyOrAssembly) - setAccessTemp = "protected internal"; - } + if (setter != null) + { + if (setter.IsPublic) + setAccessTemp = "public"; + else if (setter.IsPrivate) + setAccessTemp = "private"; + else if (setter.IsAssembly) + setAccessTemp = "internal"; + else if (setter.IsFamily) + setAccessTemp = "protected"; + else if (setter.IsFamilyOrAssembly) + setAccessTemp = "protected internal"; + } - // Are the accessibility of the getter and setter the same? - if (setAccessTemp == getAccessTemp) - { - sameAccess = true; - access = getAccessTemp; - getAccess = setAccess = String.Empty; - } - else - { - access = null; - getAccess = getAccessTemp; - setAccess = setAccessTemp; + // Are the accessibility of the getter and setter the same? + if (setAccessTemp == getAccessTemp) + { + sameAccess = true; + access = getAccessTemp; + getAccess = setAccess = String.Empty; + } + else + { + access = null; + getAccess = getAccessTemp; + setAccess = setAccessTemp; + } } } } diff --git a/docs/csharp/fundamentals/functional/snippets/deconstructing-tuples/deconstruction.csproj b/docs/csharp/fundamentals/functional/snippets/deconstructing-tuples/deconstruction.csproj index 2de6b53d97405..d816b6e17d787 100644 --- a/docs/csharp/fundamentals/functional/snippets/deconstructing-tuples/deconstruction.csproj +++ b/docs/csharp/fundamentals/functional/snippets/deconstructing-tuples/deconstruction.csproj @@ -2,7 +2,7 @@ Exe - net9.0 + net10.0 enable deconstruction.Program diff --git a/docs/csharp/how-to/index.md b/docs/csharp/how-to/index.md index 67cb38bbe6abc..67bca16daef6d 100644 --- a/docs/csharp/how-to/index.md +++ b/docs/csharp/how-to/index.md @@ -15,8 +15,8 @@ There are several tips and tricks that are common C# developer practices: - [Initialize objects using an object initializer](../programming-guide/classes-and-structs/how-to-initialize-objects-by-using-an-object-initializer.md). - [Use operator overloading](../language-reference/operators/operator-overloading.md). -- [Implement and call a custom extension method](../programming-guide/classes-and-structs/how-to-implement-and-call-a-custom-extension-method.md). -- [Create a new method for an `enum` type using extension methods](../programming-guide/classes-and-structs/how-to-create-a-new-method-for-an-enumeration.md). +- [Implement and call a custom extension member](../programming-guide/classes-and-structs/how-to-implement-and-call-a-custom-extension-method.md). +- [Create a new method for an `enum` type using extension member](../programming-guide/classes-and-structs/how-to-create-a-new-method-for-an-enumeration.md). ### Class, record, and struct members diff --git a/docs/csharp/language-reference/attributes/caller-information.md b/docs/csharp/language-reference/attributes/caller-information.md index 0196d1a3200a4..3d5f13a3ac509 100644 --- a/docs/csharp/language-reference/attributes/caller-information.md +++ b/docs/csharp/language-reference/attributes/caller-information.md @@ -58,7 +58,7 @@ The compiler injects the expression used for `condition` into the `message` argu Argument failed validation: ``` -This attribute enables you to write diagnostic utilities that provide more details. Developers can more quickly understand what changes are needed. You can also use the to determine what expression was used as the receiver for extension methods. The following method samples a sequence at regular intervals. If the sequence has fewer elements than the frequency, it reports an error: +This attribute enables you to write diagnostic utilities that provide more details. Developers can more quickly understand what changes are needed. You can also use the to determine what expression was used as the receiver for extension members. The following method samples a sequence at regular intervals. If the sequence has fewer elements than the frequency, it reports an error: :::code language="csharp" source="./snippets/CallerInformation.cs" id="ExtensionMethod"::: diff --git a/docs/csharp/language-reference/attributes/snippets/CallerInformation.cs b/docs/csharp/language-reference/attributes/snippets/CallerInformation.cs index 3c6fdc405542a..5cf69742b1339 100644 --- a/docs/csharp/language-reference/attributes/snippets/CallerInformation.cs +++ b/docs/csharp/language-reference/attributes/snippets/CallerInformation.cs @@ -56,16 +56,19 @@ public static void ValidateArgument(string parameterName, bool condition, [Calle public static class Extensions { // - public static IEnumerable Sample(this IEnumerable sequence, int frequency, - [CallerArgumentExpression(nameof(sequence))] string? message = null) + extension(IEnumerable sequence) { - if (sequence.Count() < frequency) - throw new ArgumentException($"Expression doesn't have enough elements: {message}", nameof(sequence)); - int i = 0; - foreach (T item in sequence) + public IEnumerable Sample(int frequency, + [CallerArgumentExpression(nameof(sequence))] string? message = null) { - if (i++ % frequency == 0) - yield return item; + if (sequence.Count() < frequency) + throw new InvalidOperationException($"Expression doesn't have enough elements: {message}"); + int i = 0; + foreach (T item in sequence) + { + if (i++ % frequency == 0) + yield return item; + } } } // diff --git a/docs/csharp/language-reference/attributes/snippets/attributes.csproj b/docs/csharp/language-reference/attributes/snippets/attributes.csproj index 0e8ab5607efbd..0acafad4a4eb5 100644 --- a/docs/csharp/language-reference/attributes/snippets/attributes.csproj +++ b/docs/csharp/language-reference/attributes/snippets/attributes.csproj @@ -2,7 +2,7 @@ Exe - net9.0 + net10.0 enable true enable diff --git a/docs/csharp/language-reference/builtin-types/built-in-types.md b/docs/csharp/language-reference/builtin-types/built-in-types.md index a50c0306a5645..1552091b27f1f 100644 --- a/docs/csharp/language-reference/builtin-types/built-in-types.md +++ b/docs/csharp/language-reference/builtin-types/built-in-types.md @@ -1,7 +1,7 @@ --- title: "Built-in types" description: "Learn C# built-in value and reference types" -ms.date: 03/07/2025 +ms.date: 11/24/2025 helpviewer_keywords: - "types [C#], built-in" - "built-in C# types" @@ -62,7 +62,7 @@ The C# language includes specialized rules for the ` to `System.ReadOnlySpan`, when `E` has a covariance conversion or an identity conversion to `U` - From `string` to `System.ReadOnlySpan` -The compiler never ignores any user defined conversion where an applicable *implicit span conversion* exists. Implicit span conversions can be applied to the first argument of [extension methods](../../programming-guide/classes-and-structs/extension-methods.md), the parameter with the `this` modifier. Implicit span conversions aren't considered for method group conversions. +The compiler never ignores any user defined conversion where an applicable *implicit span conversion* exists. Implicit span conversions can be applied to receiver parameter of [extension members](../../programming-guide/classes-and-structs/extension-methods.md). The receiver parameter is specified by the [`extension`](../keywords/extension.md) keyword in an extension member. The receiver parameter is the first parameter of an extension method using the `this` modifier. Implicit span conversions aren't considered for method group conversions. ## See also diff --git a/docs/csharp/language-reference/builtin-types/enum.md b/docs/csharp/language-reference/builtin-types/enum.md index 0f592c5245dbf..c68037ab98c30 100644 --- a/docs/csharp/language-reference/builtin-types/enum.md +++ b/docs/csharp/language-reference/builtin-types/enum.md @@ -1,7 +1,7 @@ --- title: "Enumeration types" description: "Learn about C# enumeration types that represent a choice or a combination of choices" -ms.date: 12/13/2019 +ms.date: 11/24/2025 f1_keywords: - "enum" - "enum_CSharpKeyword" @@ -10,7 +10,6 @@ helpviewer_keywords: - "enum type [C#]" - "enumeration type [C#]" - "bit flags [C#]" -ms.assetid: bbeb9a0f-e9b3-41ab-b0a6-c41b1a08974c --- # Enumeration types (C# reference) @@ -38,7 +37,7 @@ enum ErrorCode : ushort } ``` -You cannot define a method inside the definition of an enumeration type. To add functionality to an enumeration type, create an [extension method](../../programming-guide/classes-and-structs/extension-methods.md). +You can't define a method inside the definition of an enumeration type. To add functionality to an enumeration type, create an [extension member](../../programming-guide/classes-and-structs/extension-methods.md). The default value of an enumeration type `E` is the value produced by expression `(E)0`, even if zero doesn't have the corresponding enum member. @@ -50,7 +49,7 @@ C# allows implicit conversions from the literal value `0` to any enum type, and In the preceding example, both `port1` and `port2` are assigned the value `0`, but `GpioPort` has no member with that value. The method confirms these are invalid enum values. -This implicit conversion exists because the 0 bit pattern is the default for all struct types, including all enum types. However, it can introduce bugs in your code. To avoid these issues: +This implicit conversion exists because the 0-bit pattern is the default for all struct types, including all enum types. However, it can introduce bugs in your code. To avoid these issues: - You should almost always define a member with value `0` in your enums. - Use to validate enum values when converting from numeric types. @@ -62,7 +61,7 @@ You use an enumeration type to represent a choice from a set of mutually exclusi If you want an enumeration type to represent a combination of choices, define enum members for those choices such that an individual choice is a bit field. That is, the associated values of those enum members should be the powers of two. Then, you can use the [bitwise logical operators `|` or `&`](../operators/bitwise-and-shift-operators.md#enumeration-logical-operators) to combine choices or intersect combinations of choices, respectively. To indicate that an enumeration type declares bit fields, apply the [Flags](xref:System.FlagsAttribute) attribute to it. As the following example shows, you can also include some typical combinations in the definition of an enumeration type. -[!code-csharp[enum flags](snippets/shared/EnumType.cs#Flags)] +:::code language="csharp" source="snippets/shared/EnumType.cs" id="SnippetFlags"::: For more information and examples, see the API reference page and the [Non-exclusive members and the Flags attribute](../../../fundamentals/runtime-libraries/system-enum.md#non-exclusive-members-and-the-flags-attribute) section of the API reference page. @@ -76,7 +75,7 @@ You can use `System.Enum` in a base class constraint (that is known as the [enum For any enumeration type, there exist explicit conversions between the enumeration type and its underlying integral type. If you [cast](../operators/type-testing-and-cast.md#cast-expression) an enum value to its underlying type, the result is the associated integral value of an enum member. -[!code-csharp[enum conversions](snippets/shared/EnumType.cs#Conversions)] +:::code language="csharp" source="snippets/shared/EnumType.cs" id="SnippetConversions"::: Use the method to determine whether an enumeration type contains an enum member with the certain associated value. diff --git a/docs/csharp/language-reference/compiler-messages/cs0122.md b/docs/csharp/language-reference/compiler-messages/cs0122.md index 7de0976893ec7..860076f52f402 100644 --- a/docs/csharp/language-reference/compiler-messages/cs0122.md +++ b/docs/csharp/language-reference/compiler-messages/cs0122.md @@ -14,7 +14,7 @@ ms.assetid: 5f639a66-c807-4166-b88a-93e5f272ceb7 The [access modifier](../keywords/index.md) for a class member prevents accessing the member. For more information, see [Access Modifiers](../../programming-guide/classes-and-structs/access-modifiers.md). - [Extension methods](../../programming-guide/classes-and-structs/extension-methods.md) cannot access private members of the type they are extending. + [Extension members](../../programming-guide/classes-and-structs/extension-methods.md) cannot access private members of the type they are extending. One cause of this (not shown in the sample below) can be omitting the **/out** compiler flag on the target of a friend assembly. For more information, see [Friend Assemblies](../../../standard/assembly/friend.md) and [**OutputAssembly** (C# Compiler Options)](../compiler-options/output.md#outputassembly). diff --git a/docs/csharp/language-reference/compiler-messages/ref-modifiers-errors.md b/docs/csharp/language-reference/compiler-messages/ref-modifiers-errors.md index 448ec0708f014..30daf67e4d644 100644 --- a/docs/csharp/language-reference/compiler-messages/ref-modifiers-errors.md +++ b/docs/csharp/language-reference/compiler-messages/ref-modifiers-errors.md @@ -18,10 +18,6 @@ f1_keywords: - "CS1939" - "CS1988" - "CS7084" - - "CS8166" - - "CS8167" - - "CS8168" - - "CS8169" - "CS8196" - "CS8325" - "CS8326" @@ -32,26 +28,19 @@ f1_keywords: - "CS8332" - "CS8337" - "CS8338" - - "CS8351" - "CS8373" - - "CS8374" - "CS8388" - "CS8977" + - "CS8986" + - "CS8987" + - "CS9061" + - "CS9062" + - "CS9063" + - "CS9065" + - "CS9066" - "CS9072" - - "CS9077" - - "CS9078" - - "CS9079" - - "CS9085" - - "CS9086" - - "CS9087" - - "CS9089" - - "CS9091" - - "CS9092" - - "CS9093" - - "CS9094" - - "CS9095" - - "CS9096" - - "CS9097" + - "CS9073" + - "CS9074" - "CS9101" - "CS9102" - "CS9104" @@ -85,10 +74,6 @@ helpviewer_keywords: - "CS1939" - "CS1988" - "CS7084" - - "CS8166" - - "CS8167" - - "CS8168" - - "CS8169" - "CS8196" - "CS8325" - "CS8326" @@ -99,26 +84,19 @@ helpviewer_keywords: - "CS8332" - "CS8337" - "CS8338" - - "CS8351" - "CS8373" - - "CS8374" - "CS8388" - "CS8977" + - "CS8986" + - "CS8987" + - "CS9061" + - "CS9062" + - "CS9063" + - "CS9065" + - "CS9066" - "CS9072" - - "CS9077" - - "CS9078" - - "CS9079" - - "CS9085" - - "CS9086" - - "CS9087" - - "CS9089" - - "CS9091" - - "CS9092" - - "CS9093" - - "CS9094" - - "CS9095" - - "CS9096" - - "CS9097" + - "CS9073" + - "CS9074" - "CS9101" - "CS9102" - "CS9104" @@ -135,7 +113,8 @@ helpviewer_keywords: - "CS9201" - "CS9205" - "CS9265" -ms.date: 11/06/2024 +ai-usage: ai-assisted +ms.date: 11/21/2025 --- # Errors and warnings associated with reference parameters, variables, and returns @@ -160,10 +139,6 @@ That's by design. The text closely matches the text of the compiler error / warn - [**CS1939**](#reference-variable-restrictions): *Cannot pass the range variable as an `out` or `ref` parameter* - [**CS1988**](#reference-variable-restrictions): *Async methods cannot have `ref`, `in` or `out` parameters* - [**CS7084**](#reference-variable-restrictions): *A Windows Runtime event may not be passed as an `out` or `ref` parameter.* -- [**CS8166**](#ref-safety-violations): *Cannot return a parameter by reference because it is not a `ref` parameter* -- [**CS8167**](#ref-safety-violations): *Cannot return by reference a member of parameter because it is not a `ref` or `out` parameter* -- [**CS8168**](#ref-safety-violations): *Cannot return local by reference because it is not a ref local* -- [**CS8169**](#ref-safety-violations): *Cannot return a member of local variable by reference because it is not a ref local* - [**CS8196**](#reference-variable-restrictions): *Reference to an implicitly-typed out variable is not permitted in the same argument list.* - [**CS8325**](#reference-variable-restrictions): *'`await`' cannot be used in an expression containing a `ref` conditional operator* - [**CS8326**](#reference-variable-restrictions): *Both conditional operator values must be ref values or neither may be a ref value* @@ -174,16 +149,17 @@ That's by design. The text closely matches the text of the compiler error / warn - [**CS8332**](#writable-reference-variables-require-a-writable-referent): *Cannot assign to a member of variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* - [**CS8337**](#reference-variable-restrictions): *The first parameter of a '`ref`' extension method must be a value type or a generic type constrained to struct.* - [**CS8338**](#reference-variable-restrictions): *The first '`in`' or '`ref readonly`' parameter of the extension method must be a concrete (non-generic) value type.* -- [**CS8351**](#ref-safety-violations): *Branches of a `ref` conditional operator cannot refer to variables with incompatible declaration scopes* - [**CS8373**](#incorrect-syntax): *The left-hand side of a `ref` assignment must be a ref variable.* -- [**CS8374**](#ref-safety-violations): *Cannot ref-assign source has a narrower escape scope than destination.* - [**CS8388**](#incorrect-syntax): *An `out` variable cannot be declared as a ref local* - [**CS8977**](#reference-variable-restrictions): *Cannot use '`ref`', '`in`', or '`out`' in the signature of a method attributed with 'UnmanagedCallersOnly'.* +- [**CS8986**](#reference-variable-restrictions): *The 'scoped' modifier of parameter doesn't match target.* +- [**CS8987**](#reference-variable-restrictions): *The 'scoped' modifier of parameter doesn't match overridden or implemented member.* +- [**CS9061**](#incorrect-syntax): *The 'scoped' modifier cannot be used with discard.* +- [**CS9062**](#incorrect-syntax): *Types and aliases cannot be named 'scoped'.* +- [**CS9063**](#unscoped-ref-restrictions): *UnscopedRefAttribute cannot be applied to this parameter because it is unscoped by default.* +- [**CS9065**](#incorrect-syntax): *Do not use 'System.Runtime.CompilerServices.ScopedRefAttribute'. Use the 'scoped' keyword instead.* +- [**CS9066**](#unscoped-ref-restrictions): *UnscopedRefAttribute cannot be applied to parameters that have a 'scoped' modifier.* - [**CS9072**](#reference-variable-restrictions): *A deconstruction variable cannot be declared as a ref local* -- [**CS9077**](#ref-safety-violations): *Cannot return a parameter by reference through a `ref` parameter; it can only be returned in a return statement* -- [**CS9078**](#ref-safety-violations): *Cannot return by reference a member of parameter through a `ref` parameter; it can only be returned in a return statement* -- [**CS9079**](#ref-safety-violations): *Cannot ref-assign because source can only escape the current method through a return statement.* -- [**CS9096**](#ref-safety-violations): *Cannot ref-assign because source has a wider value escape scope than destination allowing assignment through source of values with narrower escapes scopes than destination.* - [**CS9101**](#unscoped-ref-restrictions): *UnscopedRefAttribute can only be applied to struct or virtual interface instance methods and properties, and cannot be applied to constructors or init-only members.* - [**CS9102**](#unscoped-ref-restrictions): *UnscopedRefAttribute cannot be applied to an interface implementation because implemented member doesn't have this attribute.* - [**CS9104**](#reference-variable-restrictions): *A `using` statement resource of type cannot be used in async methods or async lambda expressions.* @@ -192,16 +168,8 @@ That's by design. The text closely matches the text of the compiler error / warn The following warnings are generated when reference variables are used incorrectly: -- [**CS9085**](#ref-safety-violations): *This ref-assigns variable but destination has a narrower escape scope than source.* -- [**CS9086**](#ref-safety-violations): *The branches of the `ref` conditional operator refer to variables with incompatible declaration scopes* -- [**CS9087**](#ref-safety-violations): *This returns a parameter by reference but it is not a `ref` parameter* -- [**CS9089**](#ref-safety-violations): *This returns by reference a member of parameter that is not a `ref` or `out` parameter* -- [**CS9091**](#ref-safety-violations): *This returns local by reference but it is not a ref local* -- [**CS9092**](#ref-safety-violations): *This returns a member of local by reference but it is not a ref local* -- [**CS9093**](#ref-safety-violations): *This ref-assigns but source can only escape the current method through a return statement.* -- [**CS9094**](#ref-safety-violations): *This returns a parameter by reference through a `ref` parameter; but it can only safely be returned in a return statement* -- [**CS9095**](#ref-safety-violations): *This returns by reference a member of parameter through a `ref` parameter; but it can only safely be returned in a return statement* -- [**CS9097**](#ref-safety-violations): *This ref-assigns but source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* +- [**CS9073**](#reference-variable-restrictions): *The 'scoped' modifier of parameter doesn't match target.* +- [**CS9074**](#reference-variable-restrictions): *The 'scoped' modifier of parameter doesn't match overridden or implemented member.* - [**CS9191**](#reference-variables-require-a-referent): *The `ref` modifier for argument corresponding to `in` parameter is equivalent to `in`. Consider using `in` instead.* - [**CS9192**](#reference-variables-require-a-referent): *Argument should be passed with `ref` or `in` keyword.* - [**CS9193**](#reference-variables-require-a-referent): *Argument should be a variable because it is passed to a `ref readonly` parameter* @@ -220,7 +188,6 @@ These errors and warnings follow these themes: - ***[Language constructs where `ref` variables aren't valid](#reference-variable-restrictions)***: Some C# idioms don't allow variables. Usually this is because ref safety analysis can't be performed reliably. - ***[Value expression used where a reference variable is needed](#reference-variables-require-a-referent)***: The expression used as a reference variable must be a variable, not a value expression. - ***[Writable reference variables referring to readonly variables](#writable-reference-variables-require-a-writable-referent)***: A reference to a readonly variable can't be passed by writable reference. -- ***[violations of ref safety](#ref-safety-violations)***: A reference variable can't refer to a variable that has a narrower context. That would mean the reference variable could refer to invalid memory. This article uses the term *reference variable* as a general term for a parameter declared with one of the `in`, `ref readonly`, `ref`, or `out` modifiers, or a `ref` local variable, a `ref` field in a `ref struct`, or a `ref` return. A reference variable refers to another variable, called the *referent*. @@ -233,12 +200,14 @@ These errors indicate that you're using incorrect syntax regarding reference var - **CS9190**: *`readonly` modifier must be specified after `ref`.* - **CS9205**: *Expected interpolated string.* -You can correct the error with one of these changes: +To correct these errors: -- The left operand of an `= ref` operator must be a reference variable. For more information on the correct syntax, see [reference variables](../statements/declarations.md#reference-variables). -- The parameter modifier `ref readonly` must be in that order. `readonly ref` is not a legal parameter modifier. Switch the order of the words. -- A local variable can't be declared as `out`. To declare a local reference variable, use `ref`. -- An `out` argument can't be an interpolated string. +- Ensure the left operand of a `= ref` operator is a reference variable rather than a value expression or non-reference local. Ref assignment requires both sides to be reference variables that can create an alias to the same storage location (**CS8373**). +- When declaring reference parameters, write the modifier as `ref readonly` rather than `readonly ref`. The C# language specification requires the `ref` keyword to precede the `readonly` modifier in parameter declarations to maintain consistent syntax across all reference parameter types (**CS9190**). +- Use the `ref` keyword instead of `out` when declaring local reference variables. `out` is exclusively a parameter modifier that indicates a method must assign a value before returning, whereas `ref` is the appropriate keyword for creating local variables that alias other storage locations (**CS8388**). +- Pass a regular variable or value expression instead of an interpolated string when calling a method with an `out` parameter. Interpolated strings are immutable temporary values that can't be used as output parameters since they don't represent assignable storage locations (**CS9205**). + +For more information about reference variables and their syntax requirements, see [reference variables](../statements/declarations.md#reference-variables) and the [C# Language Specification](~/_csharpstandard/standard/variables.md#97-reference-variables-and-returns). ## Reference variable restrictions @@ -271,31 +240,41 @@ The following warnings indicate that a reference variable shouldn't be used, and - **CS9201**: *Ref field should be ref-assigned before use.* - **CS9265**: *Field is never ref-assigned to, and will always have its default value (null reference)* -To fix the error, remove the reference variable where it isn't allowed: - -- Remove `in`, `ref`, and `out` parameters from [indexers](../../programming-guide/indexers/index.md), [iterators](../../iterators.md), and [async methods](../../asynchronous-programming/index.md). -- Remove [ref conditional expressions](../operators/conditional-operator.md#conditional-ref-expression) (`? :`) that include an [await](../operators/await.md). -- Remove the `ref` modifier from the first parameter of a [extension method](../../programming-guide/classes-and-structs/extension-methods.md) where that type isn't a value type or a generic type constrained as a value type. -- Either both or neither [conditional operator expressions] must be `ref` variables. Either remove `ref` from one expression, or add it to the other. If it's a `ref` conditional expression, both expressions must be the same type. -- `ref` and `out` parameters can't have [default values](../../programming-guide/classes-and-structs/named-and-optional-arguments.md). Either remove the `ref` or `out` modifier, or remove the default value. -- An implicitly typed `out` variable declaration can't also appear elsewhere in the same argument list. -- You can't put reference variables in a `using` statement in `async` methods lambda expressions. -- The range variable in a [LINQ query expression](../../linq/get-started/query-expression-basics.md) can't be passed by reference. -- You can't deconstruct an object into reference variables. Replace the reference variables with value variables. -- You can't implement multiple interfaces where method overloads differ only on `ref` and `out`. For example, one interface declares `void M(ref int i)` and another interface declares `void M(out int i)`. A class can't implement both interfaces because the methods aren't distinguishable. You can only implement one of those interfaces. -- Methods attributed with can't use reference parameters. -- A Windows runtime event can't be passed as a reference variable. -- A `ref readonly` parameter can't have the applied to it in remoting API. -- Initialize a `ref` field in the constructor or as a field initializer. +To correct these errors: + +- Remove reference parameters from [indexers](../../programming-guide/indexers/index.md). Indexers are designed to provide array-like access syntax and the compiler can't guarantee safe lifetime tracking for references passed through indexer accessors (**CS0631**, **CS1623**). +- Remove reference parameters from [iterator methods](../../iterators.md). Iterators execute code lazily across multiple calls using state machines, and the compiler can't ensure referenced variables remain valid across yield return boundaries where execution is suspended and resumed (**CS1623**). +- Remove reference parameters from [async methods](../../asynchronous-programming/index.md). Async methods might suspend execution at await points and resume on different threads, making it impossible to guarantee that referenced variables remain valid and accessible throughout the method's execution (**CS1988**). +- Avoid using [await expressions](../operators/await.md) inside [ref conditional expressions](../operators/conditional-operator.md#conditional-ref-expression). The await operation might suspend execution and invalidate the references being selected by the conditional operator, leading to potential use of invalidated references when execution resumes (**CS8325**). +- Ensure both branches of a ref conditional operator return references or neither returns a reference, and when both are references they must be the same type. The conditional operator must produce a consistent result type that can be safely used by the calling code regardless of which branch is selected (**CS8326**, **CS8327**). +- Remove default values from `ref` and `out` parameters. Reference parameters must always be provided at the call site to establish the required aliasing relationship between the parameter and an existing variable, making default values semantically meaningless (**CS1741**). +- Avoid declaring an implicitly typed `out` variable in an argument list that also references that same variable. The compiler must infer the variable's type from the method signature while simultaneously validating uses of that variable within the same expression, creating a circular dependency (**CS8196**). +- Don't pass [LINQ query](../../linq/get-started/query-expression-basics.md) range variables as reference parameters. Range variables are compiler-generated iteration variables whose lifetime is managed by the query execution model and don't have stable memory locations that can be safely referenced (**CS1939**). +- Use regular value variables instead of ref locals when [deconstructing](../operators/patterns.md#positional-pattern) objects. Deconstruction creates new variables to receive the deconstructed values and reference variables would attempt to alias these temporary values rather than store them independently (**CS9072**). +- Avoid implementing multiple interfaces where methods differ only by `ref` versus `out` modifiers on parameters. The C# language specification treats these as distinct signatures but doesn't provide a way to disambiguate which implementation to call since both `ref` and `out` share the same calling syntax at implementation boundaries (**CS0767**). +- Remove reference parameters from methods decorated with . These methods are callable from unmanaged code that doesn't understand C#'s reference safety rules and can't guarantee proper lifetime management of referenced variables across the managed/unmanaged boundary (**CS8977**). +- Use the `ref` modifier on [extension method](../../programming-guide/classes-and-structs/extension-methods.md) first parameters only for value types or generic types constrained to value types. Reference types are already passed by reference at the CLR level and adding `ref` would create a reference to a reference, while value type extensions with `ref` enable mutation of the extended instance (**CS8337**, **CS8338**). +- Don't pass Windows Runtime events as reference parameters. These events follow the Windows Runtime type system, which has different lifetime and threading semantics than .NET references and doesn't support the aliasing behavior required by C# reference parameters (**CS7084**). +- Remove the from `ref readonly` parameters. This attribute is designed for marshaling semantics in platform invoke scenarios where the parameter direction is outbound only, which conflicts with `ref readonly`'s guarantee that the parameter references existing data that won't be reassigned (**CS9199**). +- Ensure all `ref` fields in a type are assigned either in field initializers or in all constructor code paths before the constructor completes. Uninitialized ref fields would contain invalid references that could lead to memory corruption if accessed (**CS9201**, **CS9265**). +- Match the reference kind modifiers (`ref`, `in`, `out`, `ref readonly`) between a method and its overridden base method or implemented interface method. The reference modifier is part of the method signature contract that derived types must honor to maintain substitutability and caller expectations (**CS9196**, **CS9197**, **CS9198**). +- Declare parameters as `in` rather than `ref readonly` when providing default values. `ref readonly` is designed for scenarios where the caller passes a reference to an existing variable, whereas `in` parameters can accept both references and temporary copies of values, making default values meaningful (**CS9200**). + +For more information about where reference variables are allowed, see [Method parameters](../keywords/method-parameters.md), [Iterators](../../iterators.md), [Asynchronous programming patterns](../../asynchronous-programming/index.md), and the [C# Language Specification](~/_csharpstandard/standard/variables.md#97-reference-variables-and-returns). ## `unscoped ref` restrictions The `unscoped` qualifier on `ref` parameters isn't allowed in some locations: -- **CS9101**: *UnscopedRefAttribute can only be applied to struct instance or virtual interface methods and properties, and cannot be applied to constructors or or init-only members.* -- **CS9102**: *UnscopedRefAttribute cannot be applied to an interface implementation because implemented member doesn't have this attribute..* +- **CS9101**: *UnscopedRefAttribute can only be applied to struct instance or virtual interface methods and properties, and cannot be applied to constructors or init-only members.* +- **CS9102**: *UnscopedRefAttribute cannot be applied to an interface implementation because implemented member doesn't have this attribute.* + +To correct these errors: + +- Remove the `unscoped` modifier or the attribute from struct constructors and init-only members. These members have special initialization semantics where the compiler must ensure that any references don't outlive the initialization phase, and allowing unscoped references would violate the guarantee that initialization completes before the struct becomes fully accessible (**CS9101**). +- Remove the `unscoped` modifier from interface implementation methods when the corresponding interface method doesn't have it. The unscoped characteristic affects the method's contract regarding reference lifetime guarantees, and implementations must maintain the same contract as the interface they're implementing to ensure callers can rely on consistent lifetime behavior regardless of which implementation is invoked (**CS9102**). -You must remove the `unscoped` modifier on the parameter declaration that caused the error. +For more information about scoped and unscoped references, see [Method parameters](../keywords/method-parameters.md) and the [low-level struct improvements](~/_csharplang/proposals/csharp-11.0/low-level-struct-improvements.md) feature specification. ## Reference variables require a referent @@ -311,7 +290,13 @@ Warnings: - **CS9193**: *Argument should be a variable because it is passed to a `ref readonly` parameter* - **CS9195**: *Argument should be passed with the `in` keyword* -The compiler emits these errors when you use an expression that calculates a value where a variable must be used. You must store the result of that expression in a variable to use it. For example, properties and indexers return values, not variables. You must store the result in a variable and pass a reference to that variable. +To correct these errors: + +- Store the result of a property or indexer access in a local variable before passing it as a reference parameter. [Properties](../../programming-guide/classes-and-structs/properties.md) and [indexers](../../programming-guide/indexers/index.md) are methods that return values rather than providing direct access to storage locations, and reference parameters require an actual variable with a stable memory location that can be aliased (**CS0206**, **CS1510**). +- Use the `in` modifier instead of `ref` when passing arguments to `in` parameters. While `ref` technically works due to backward compatibility, the `in` modifier more clearly expresses the intent that the argument is read-only and may be passed more efficiently as a reference without copying (**CS9191**, **CS9195**). +- Add the appropriate reference modifier (`ref`, `in`, or `ref readonly`) when passing arguments to parameters that expect references. Omitting the modifier might cause the compiler to create a temporary copy of the value, which is inefficient and can lead to unexpected behavior if the calling code expects modifications to be reflected in the original variable (**CS9192**, **CS9193**). + +For more information about reference parameters and passing variables by reference, see [Method parameters](../keywords/method-parameters.md), [ref keyword](../keywords/ref.md), and the [C# Language Specification](~/_csharpstandard/standard/variables.md#97-reference-variables-and-returns). ## Writable reference variables require a writable referent @@ -329,43 +314,11 @@ A writable reference variable requires that the referent also is writable. The f - **CS8331**: *Cannot assign to variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* - **CS8332**: *Cannot assign to a member of variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* -Examples of variables that aren't writable include: - -- [readonly](../../language-reference/keywords/readonly.md) fields, both instance and static fields. -- Members of `readonly` fields. -- The `this` variable. -- The [foreach](../../language-reference/statements/iteration-statements.md#the-foreach-statement) iteration variable -- A [using](../../language-reference/statements/using.md) variable, or a [fixed](../../language-reference/statements/fixed.md) variable. +To correct these errors: -You must copy the value and pass a reference to the copy. - -## Ref safety violations - -The compiler tracks the safe context of referents and reference variables. The compiler issues errors, or warnings in unsafe code, when a reference variable refers to a referent variable that's no longer valid. The referent must have a safe context that is at least as wide as the ref safe context of The reference variable. Violating these safety checks means the reference variable accesses random memory instead of the referent variable. - -- **CS8166**: *Cannot return a parameter by reference because it is not a `ref` parameter* -- **CS8167**: *Cannot return by reference a member of parameter because it is not a `ref` or `out` parameter* -- **CS8168**: *Cannot return local by reference because it is not a ref local* -- **CS8169**: *Cannot return a member of local variable by reference because it is not a ref local* -- **CS8345**: *Field or auto-implemented property cannot be of type unless it is an instance member of a `ref struct`.* -- **CS8351**: *Branches of a `ref` conditional operator cannot refer to variables with incompatible declaration scopes* -- **CS8374**: *Cannot ref-assign source has a narrower escape scope than destination.* -- **CS9077**: *Cannot return a parameter by reference through a `ref` parameter; it can only be returned in a return statement* -- **CS9078**: *Cannot return by reference a member of parameter through a `ref` parameter; it can only be returned in a return statement* -- **CS9079**: *Cannot ref-assign source to destination because source can only escape the current method through a return statement.* -- **CS9096**: *Cannot ref-assign source to destination because source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* - -Warnings: +- Copy the value from a [readonly field](../keywords/readonly.md) to a local variable and pass the local variable as a `ref` or `out` parameter. Readonly fields are immutable after initialization (except within constructors) and allowing writable references to them would violate the immutability guarantee that readonly provides (**CS0192**, **CS0199**, **CS1649**, **CS1651**). +- Use `ref readonly` or `in` parameters instead of `ref` or `out` when you need to pass readonly variables, iteration variables, or other non-writable values by reference. These modifiers indicate that the method will only read the referenced value without attempting to modify it. That aligns with the immutability constraints of the original variable (**CS1605**, **CS1655**, **CS1657**, **CS8329**). +- Copy members of readonly variables to local variables before passing them as writable references. Even though the member itself might not be declared as readonly, it's accessed through a readonly path (via a readonly field, `in` parameter, or `ref readonly` local), and the compiler enforces transitivity of readonly-ness to prevent indirect mutation of readonly data (**CS8330**, **CS8332**). +- Avoid writable ref assignments to readonly variables, [foreach iteration variables](../statements/iteration-statements.md#the-foreach-statement), [using statement resources](../statements/using.md), or [fixed statement variables](../statements/fixed.md). These variables have special lifetime semantics managed by the compiler. The variable is automatically finalized or disposed at the end of its scope. External references create dangling references after disposal (**CS8331**). -- **CS9085**: *This ref-assigns source to destination but source has a narrower escape scope than destination.* -- **CS9086**: *The branches of the ref conditional operator refer to variables with incompatible declaration scopes* -- **CS9087**: *This returns a parameter by reference but it is not a `ref` parameter* -- **CS9089**: *This returns by reference a member of parameter that is not a `ref` or `out` parameter* -- **CS9091**: *This returns local by reference but it is not a ref local* -- **CS9092**: *This returns a member of local by reference but it is not a ref local* -- **CS9093**: *This ref-assigns source to destination but source can only escape the current method through a return statement.* -- **CS9094**: *This returns a parameter by reference through a `ref` parameter; but it can only safely be returned in a return statement* -- **CS9095**: *This returns by reference a member of parameter through a `ref` parameter; but it can only safely be returned in a return statement* -- **CS9097**: *This ref-assigns source to destination but source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* - -The compiler uses static analysis to determine if the referent is valid at all points where the reference variable can be used. You need to refactor code so that the referent remains valid at all locations where the reference variable might refer to it. For details on the rules for ref safety, see the C# standard on [ref safe contexts](~/_csharpstandard/standard/variables.md#972-ref-safe-contexts). +For more information about readonly semantics and reference parameters, see [readonly keyword](../keywords/readonly.md), [in parameter modifier](../keywords/method-parameters.md#in-parameter-modifier), [ref readonly](../statements/declarations.md#reference-variables), and the [C# Language Specification](~/_csharpstandard/standard/variables.md#97-reference-variables-and-returns). diff --git a/docs/csharp/language-reference/compiler-messages/ref-safety-errors.md b/docs/csharp/language-reference/compiler-messages/ref-safety-errors.md new file mode 100644 index 0000000000000..93d5741e6492d --- /dev/null +++ b/docs/csharp/language-reference/compiler-messages/ref-safety-errors.md @@ -0,0 +1,211 @@ +--- +title: Errors and warnings related to ref safety +description: The compiler issues these errors and warnings when the referent of a reference variable might not be valid. These errors prevent you from creating dangling references. +f1_keywords: + - "CS8166" + - "CS8167" + - "CS8168" + - "CS8169" + - "CS8345" + - "CS8351" + - "CS8374" + - "CS9075" + - "CS9076" + - "CS9077" + - "CS9078" + - "CS9079" + - "CS9080" + - "CS9081" + - "CS9082" + - "CS9083" + - "CS9084" + - "CS9085" + - "CS9086" + - "CS9087" + - "CS9088" + - "CS9089" + - "CS9090" + - "CS9091" + - "CS9092" + - "CS9093" + - "CS9094" + - "CS9095" + - "CS9096" + - "CS9097" +helpviewer_keywords: + - "CS8166" + - "CS8167" + - "CS8168" + - "CS8169" + - "CS8345" + - "CS8351" + - "CS8374" + - "CS9075" + - "CS9076" + - "CS9077" + - "CS9078" + - "CS9079" + - "CS9080" + - "CS9081" + - "CS9082" + - "CS9083" + - "CS9084" + - "CS9085" + - "CS9086" + - "CS9087" + - "CS9088" + - "CS9089" + - "CS9090" + - "CS9091" + - "CS9092" + - "CS9093" + - "CS9094" + - "CS9095" + - "CS9096" + - "CS9097" +ai-usage: ai-assisted +ms.date: 11/21/2025 +--- +# Errors and warnings related to ref safety + +The following errors can be generated when reference variable safety rules are violated: + + +- [**CS8166**](#returning-references-with-incompatible-scopes): *Cannot return a parameter by reference because it is not a `ref` parameter* +- [**CS8167**](#returning-references-with-incompatible-scopes): *Cannot return by reference a member of parameter because it is not a `ref` or `out` parameter* +- [**CS8168**](#returning-references-with-incompatible-scopes): *Cannot return local by reference because it is not a ref local* +- [**CS8169**](#returning-references-with-incompatible-scopes): *Cannot return a member of local variable by reference because it is not a ref local* +- [**CS8345**](#struct-member-and-field-restrictions): *Field or auto-implemented property cannot be of type unless it is an instance member of a `ref struct`.* +- [**CS8351**](#escape-scope-violations-and-conditional-operators): *Branches of a `ref` conditional operator cannot refer to variables with incompatible declaration scopes* +- [**CS8374**](#ref-assignments-with-incompatible-scopes): *Cannot ref-assign source has a narrower escape scope than destination.* +- [**CS9075**](#returning-references-with-incompatible-scopes): *Cannot return a parameter by reference because it is scoped to the current method* +- [**CS9076**](#returning-references-with-incompatible-scopes): *Cannot return by reference a member of parameter because it is scoped to the current method* +- [**CS9077**](#returning-references-with-incompatible-scopes): *Cannot return a parameter by reference through a `ref` parameter; it can only be returned in a return statement* +- [**CS9078**](#returning-references-with-incompatible-scopes): *Cannot return by reference a member of parameter through a `ref` parameter; it can only be returned in a return statement* +- [**CS9079**](#ref-assignments-with-incompatible-scopes): *Cannot ref-assign source to destination because source can only escape the current method through a return statement.* +- [**CS9096**](#ref-assignments-with-incompatible-scopes): *Cannot ref-assign source to destination because source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* + +The following warnings are generated when reference variable safety rules are violated: + +- [**CS9080**](#escape-scope-violations-and-conditional-operators): *Use of variable in this context may expose referenced variables outside of their declaration scope* +- [**CS9081**](#escape-scope-violations-and-conditional-operators): *A result of a stackalloc expression of type in this context may be exposed outside of the containing method* +- [**CS9082**](#struct-member-and-field-restrictions): *Local is returned by reference but was initialized to a value that cannot be returned by reference* +- [**CS9083**](#struct-member-and-field-restrictions): *A member is returned by reference but was initialized to a value that cannot be returned by reference* +- [**CS9084**](#struct-member-and-field-restrictions): *Struct member returns 'this' or other instance members by reference* +- [**CS9085**](#ref-assignments-with-incompatible-scopes): *This ref-assigns source to destination but source has a narrower escape scope than destination.* +- [**CS9086**](#escape-scope-violations-and-conditional-operators): *The branches of the ref conditional operator refer to variables with incompatible declaration scopes* +- [**CS9087**](#returning-references-with-incompatible-scopes): *This returns a parameter by reference but it is not a `ref` parameter* +- [**CS9088**](#returning-references-with-incompatible-scopes): *This returns a parameter by reference but it is scoped to the current method* +- [**CS9089**](#returning-references-with-incompatible-scopes): *This returns by reference a member of parameter that is not a `ref` or `out` parameter* +- [**CS9090**](#returning-references-with-incompatible-scopes): *This returns by reference a member of parameter that is scoped to the current method* +- [**CS9091**](#returning-references-with-incompatible-scopes): *This returns local by reference but it is not a ref local* +- [**CS9092**](#returning-references-with-incompatible-scopes): *This returns a member of local by reference but it is not a ref local* +- [**CS9093**](#ref-assignments-with-incompatible-scopes): *This ref-assigns source to destination but source can only escape the current method through a return statement.* +- [**CS9094**](#returning-references-with-incompatible-scopes): *This returns a parameter by reference through a `ref` parameter; but it can only safely be returned in a return statement* +- [**CS9095**](#returning-references-with-incompatible-scopes): *This returns by reference a member of parameter through a `ref` parameter; but it can only safely be returned in a return statement* +- [**CS9097**](#ref-assignments-with-incompatible-scopes): *This ref-assigns source to destination but source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* + +## Returning references with incompatible scopes + +The compiler prevents you from returning a reference to a variable when the variable's lifetime doesn't extend beyond the method's scope. These errors occur when attempting to return by reference a parameter, local variable, or member that isn't declared with `ref` or has a scope limited to the current method. + +Errors: + +- **CS8166**: *Cannot return a parameter by reference because it is not a `ref` parameter* +- **CS8167**: *Cannot return by reference a member of parameter because it is not a `ref` or `out` parameter* +- **CS8168**: *Cannot return local by reference because it is not a ref local* +- **CS8169**: *Cannot return a member of local variable by reference because it is not a ref local* +- **CS9075**: *Cannot return a parameter by reference because it is scoped to the current method* +- **CS9076**: *Cannot return by reference a member of parameter because it is scoped to the current method* +- **CS9077**: *Cannot return a parameter by reference through a `ref` parameter; it can only be returned in a return statement* +- **CS9078**: *Cannot return by reference a member of parameter through a `ref` parameter; it can only be returned in a return statement* + +Warnings: + +- **CS9087**: *This returns a parameter by reference but it is not a `ref` parameter* +- **CS9088**: *This returns a parameter by reference but it is scoped to the current method* +- **CS9089**: *This returns by reference a member of parameter that is not a `ref` or `out` parameter* +- **CS9090**: *This returns by reference a member of parameter that is scoped to the current method* +- **CS9091**: *This returns local by reference but it is not a ref local* +- **CS9092**: *This returns a member of local by reference but it is not a ref local* +- **CS9094**: *This returns a parameter by reference through a `ref` parameter; but it can only safely be returned in a return statement* +- **CS9095**: *This returns by reference a member of parameter through a `ref` parameter; but it can only safely be returned in a return statement* + +To resolve these errors: + +- Change the method signature to declare parameters with the `ref` keyword instead of passing them by value, which allows the parameter's storage location to be returned safely because the caller controls the variable's lifetime (**CS8166**, **CS8167**, **CS9087**, **CS9089**). +- For local variables, declare them as `ref` locals by assigning them from a ref-returning expression or a ref parameter, which ensures the local refers to storage with a sufficient lifetime rather than creating a new variable with method-scoped lifetime (**CS8168**, **CS8169**, **CS9091**, **CS9092**). +- When a parameter is declared with the `scoped` modifier, avoid returning it by reference because the `scoped` modifier explicitly restricts the parameter's reference from escaping the method, preventing potential dangling references (**CS9075**, **CS9076**, **CS9088**, **CS9090**). +- If you need to return a reference that comes from a `ref` parameter, use a direct `return ref` statement rather than assigning the reference to another `ref` parameter and returning that, because the compiler can only track the escape scope through direct return statements (**CS9077**, **CS9078**, **CS9094**, **CS9095**). + +For more information about ref safety rules, see the article on [ref returns](../statements/jump-statements.md#ref-returns) and the C# standard section on [ref safe contexts](~/_csharpstandard/standard/variables.md#972-ref-safe-contexts). + +## Ref assignments with incompatible scopes + +The compiler prevents ref assignment operations where the source variable has a narrower escape scope than the destination. A ref assignment creates a reference from the destination to the source's storage location. If the source could go out of scope before the destination, the destination would refer to invalid memory. + +Errors: + +- **CS8374**: *Cannot ref-assign source has a narrower escape scope than destination.* +- **CS9079**: *Cannot ref-assign source to destination because source can only escape the current method through a return statement.* +- **CS9096**: *Cannot ref-assign source to destination because source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* + +Warnings: + +- **CS9085**: *This ref-assigns source to destination but source has a narrower escape scope than destination.* +- **CS9093**: *This ref-assigns source to destination but source can only escape the current method through a return statement.* +- **CS9097**: *This ref-assigns source to destination but source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* + +To resolve these errors: + +- Restructure your code so that the source variable in a ref assignment has an escape scope at least as wide as the destination variable, which ensures the destination reference remains valid for its entire lifetime and prevents dangling references (**CS8374**, **CS9085**). +- When a variable can only escape the method through a return statement, don't assign it to `ref` variables accessed through other means. Examples include storing in fields or returning through ref parameters. Those actions violate the restriction that the source can only be used in return statements (**CS9079**, **CS9093**). +- For ref assignments involving value escape scopes, ensure the source's value escape scope isn't wider than the destination's, because a mismatch would allow you to assign narrower-scoped values through the destination reference, potentially creating references to short-lived values (**CS9096**, **CS9097**). + +For more information about ref safety rules, see the article on [ref returns](../statements/jump-statements.md#ref-returns) and the C# standard section on [ref safe contexts](~/_csharpstandard/standard/variables.md#972-ref-safe-contexts). + +## Escape scope violations and conditional operators + +The compiler tracks how variables can escape their declaration scope through various operations. These errors occur when using variables in contexts that could expose referenced variables outside their valid lifetime, including ref conditional operators and stackalloc expressions. + +Errors: + +- **CS8351**: *Branches of a `ref` conditional operator cannot refer to variables with incompatible declaration scopes* + +Warnings: + +- **CS9080**: *Use of variable in this context may expose referenced variables outside of their declaration scope* +- **CS9081**: *A result of a stackalloc expression of type in this context may be exposed outside of the containing method* +- **CS9086**: *The branches of the ref conditional operator refer to variables with incompatible declaration scopes* + +To resolve these errors: + +- Modify the ref conditional operator (the `?:` operator with `ref` returns) so that both the true and false branches refer to variables that have compatible declaration scopes, which means both variables must have lifetimes that extend to at least the same scope level, preventing the conditional expression from potentially returning a reference that becomes invalid (**CS8351**, **CS9086**). +- When using variables in expressions or method calls, ensure the context doesn't allow referenced variables to escape beyond their declaration scope, which typically means avoiding passing scoped variables to methods or expressions where they might be captured or stored beyond their intended lifetime (**CS9080**). +- For stackalloc expressions, avoid assigning the result to variables or using it in contexts where the stack-allocated memory could be accessed outside the containing method, because stack-allocated memory is automatically freed when the method returns and accessing it afterward results in undefined behavior (**CS9081**). + +For more information, see the article on [ref returns](../statements/jump-statements.md#ref-returns), the article on [memory usage](../../../standard/memory-and-spans/memory-t-usage-guidelines.md), and the C# standard section on [ref safe contexts](~/_csharpstandard/standard/variables.md#972-ref-safe-contexts). + +## Struct member and field restrictions + +The compiler enforces special rules for struct members and fields to prevent dangling references. These errors occur when struct members return references to instance state or when fields have types that require special handling. + +Errors: + +- **CS8345**: *Field or auto-implemented property cannot be of type unless it is an instance member of a `ref struct`.* + +Warnings: + +- **CS9082**: *Local is returned by reference but was initialized to a value that cannot be returned by reference* +- **CS9083**: *A member is returned by reference but was initialized to a value that cannot be returned by reference* +- **CS9084**: *Struct member returns 'this' or other instance members by reference* + +To resolve these errors: + +- Ensure that fields and auto-implemented properties with ref-like types (such as `Span` or `ref struct` types) are only declared as instance members within a ref struct rather than in regular structs or classes, because ref-like types can only safely exist on the stack and ref structs provide the necessary lifetime guarantees (**CS8345**). +- When returning a local variable by reference from a method, verify that the local was initialized from a source that has a sufficient escape scope such as a ref parameter or ref-returning method call, rather than from a value-typed expression or local-scoped variable that would create a reference to short-lived storage (**CS9082**, **CS9083**). +- In struct instance methods or properties, avoid returning `this` or any instance fields by reference, because structs are value types that are often copied, and returning a reference to an instance member could create a reference to a temporary copy destroyed after the method returns (**CS9084**). + +For more information, see the article on [ref struct types](../../language-reference/builtin-types/ref-struct.md) and the C# standard section on [ref safe contexts](~/_csharpstandard/standard/variables.md#972-ref-safe-contexts). diff --git a/docs/csharp/language-reference/keywords/method-parameters.md b/docs/csharp/language-reference/keywords/method-parameters.md index 74234dae906cb..7089434872abe 100644 --- a/docs/csharp/language-reference/keywords/method-parameters.md +++ b/docs/csharp/language-reference/keywords/method-parameters.md @@ -80,7 +80,7 @@ You can't use the previous parameter modifiers in the following kinds of methods - Async methods, which you define by using the [async](async.md) modifier. - Iterator methods, which include a [yield return](../statements/yield.md) or `yield break` statement. -[Extension methods](../../programming-guide/classes-and-structs/extension-methods.md) also have restrictions on the use of these argument keywords: +[Extension members](../../programming-guide/classes-and-structs/extension-methods.md) also have restrictions on the use of these argument keywords: - The `out` keyword can't be used on the first argument of an extension method. - The `ref` keyword can't be used on the first argument of an extension method when the argument isn't a `struct`, or a generic type not constrained to be a struct. diff --git a/docs/csharp/language-reference/keywords/snippets/GenericWhereConstraints.cs b/docs/csharp/language-reference/keywords/snippets/GenericWhereConstraints.cs index 154d3d6cba2c0..73ad9d5eee8c8 100644 --- a/docs/csharp/language-reference/keywords/snippets/GenericWhereConstraints.cs +++ b/docs/csharp/language-reference/keywords/snippets/GenericWhereConstraints.cs @@ -3,8 +3,6 @@ using System.Collections.Generic; using System.Text; -using static Keywords.UnmanagedExtensions; - namespace Keywords { // @@ -84,213 +82,11 @@ public void MyMethod(T t) where T : IMyInterface { } // } - // - public class Employee - { - public Employee(string s, int i) => (Name, ID) = (s, i); - public string Name { get; set; } - public int ID { get; set; } - } - - public class GenericList where T : Employee - { - private class Node - { - public Node(T t) => (Next, Data) = (null, t); - - public Node Next { get; set; } - public T Data { get; set; } - } - - private Node head; - - public void AddHead(T t) - { - Node n = new Node(t) { Next = head }; - head = n; - } - - public IEnumerator GetEnumerator() - { - Node current = head; - - while (current != null) - { - yield return current.Data; - current = current.Next; - } - } - - public T FindFirstOccurrence(string s) - { - Node current = head; - T t = null; - - while (current != null) - { - //The constraint enables access to the Name property. - if (current.Data.Name == s) - { - t = current.Data; - break; - } - else - { - current = current.Next; - } - } - return t; - } - } - // public interface IEmployee { } - // - class EmployeeList where T : Employee, IEmployee, System.IComparable, new() - { - // ... - } - // - - // - class Base { } - class Test - where U : struct - where T : Base, new() - { } - // - - namespace ListExample - { - // - public class List - { - public void Add(List items) where U : T {/*...*/} - } - // - } - - // - //Type parameter V is used as a type constraint. - public class SampleClass where T : V { } - // - - public static class UnmanagedExtensions - { - // - unsafe public static byte[] ToByteArray(this T argument) where T : unmanaged - { - var size = sizeof(T); - var result = new Byte[size]; - Byte* p = (byte*)&argument; - for (var i = 0; i < size; i++) - result[i] = *p++; - return result; - } - // - - // - public static TDelegate TypeSafeCombine(this TDelegate source, TDelegate target) - where TDelegate : System.Delegate - => Delegate.Combine(source, target) as TDelegate; - // - - // - public static Dictionary EnumNamedValues() where T : System.Enum - { - var result = new Dictionary(); - var values = Enum.GetValues(typeof(T)); - - foreach (int item in values) - result.Add(item, Enum.GetName(typeof(T), item)); - return result; - } - // - } - public static class GenericWhereConstraints - { - public static void Examples() - { - TestStringEquality(); - TestUnmanaged(); - TestDelegateCombination(); - TestEnumValues(); - } - - // - public static void OpEqualsTest(T s, T t) where T : class - { - System.Console.WriteLine(s == t); - } - private static void TestStringEquality() - { - string s1 = "target"; - System.Text.StringBuilder sb = new System.Text.StringBuilder("target"); - string s2 = sb.ToString(); - OpEqualsTest(s1, s2); - } - // - - public struct Point3D - { - public double X { get; set; } - public double Y { get; set; } - public double Z { get; set; } - } - private static void TestUnmanaged() - { - var thing = new Point3D { X = 1, Y = 2, Z = 3 }; - - var storage = thing.ToByteArray(); - - for (int i = 0; i < storage.Length; i++) - Console.Write($"{storage[i]:X2}, "); - Console.WriteLine(); - } - - private static void TestDelegateCombination() - { - // - Action first = () => Console.WriteLine("this"); - Action second = () => Console.WriteLine("that"); - - var combined = first.TypeSafeCombine(second); - combined(); - - Func test = () => true; - // Combine signature ensures combined delegates must - // have the same type. - //var badCombined = first.TypeSafeCombine(test); - // - } - - // - enum Rainbow - { - Red, - Orange, - Yellow, - Green, - Blue, - Indigo, - Violet - } - // - private static void TestEnumValues() - { - // - var map = EnumNamedValues(); - - foreach (var pair in map) - Console.WriteLine($"{pair.Key}:\t{pair.Value}"); - - // - } - } - // public abstract class B { diff --git a/docs/csharp/language-reference/keywords/snippets/Program.cs b/docs/csharp/language-reference/keywords/snippets/Program.cs index 338dbd7afa91e..cc724a7ef5d9c 100644 --- a/docs/csharp/language-reference/keywords/snippets/Program.cs +++ b/docs/csharp/language-reference/keywords/snippets/Program.cs @@ -8,8 +8,6 @@ class Program { static async Task Main(string[] args) { - Console.WriteLine("================= Generic Where Constraints Examples ======================"); - GenericWhereConstraints.Examples(); Console.WriteLine("================= readonly Keyword Examples ======================"); ReadonlyKeywordExamples.Examples(); Console.WriteLine("================= pass by value / reference Keyword Examples ======================"); diff --git a/docs/csharp/language-reference/keywords/this.md b/docs/csharp/language-reference/keywords/this.md index 87cad355b6d9e..41ebf325ffc61 100644 --- a/docs/csharp/language-reference/keywords/this.md +++ b/docs/csharp/language-reference/keywords/this.md @@ -13,7 +13,7 @@ helpviewer_keywords: The `this` keyword refers to the current instance of the class and is also used as a modifier of the first parameter of an extension method. > [!NOTE] -> This article discusses the use of `this` with class instances. For more information about its use in extension methods, see the [`extension`](./extension.md) keyword. +> This article discusses the use of `this` to refer to the receiver instance in the current member. For more information about its use in extension methods, see the [`extension`](./extension.md) keyword. The following are common uses of `this`: diff --git a/docs/csharp/language-reference/keywords/using-directive.md b/docs/csharp/language-reference/keywords/using-directive.md index 60c46dfd5f1fc..5838320f2e559 100644 --- a/docs/csharp/language-reference/keywords/using-directive.md +++ b/docs/csharp/language-reference/keywords/using-directive.md @@ -1,7 +1,7 @@ --- description: "The `using` directive imports types from a namespace, or creates an alias for a given type. Using directives enable you to use simple names for types instead of the fully qualified type name." title: "The using directive: Import types from a namespace" -ms.date: 01/27/2025 +ms.date: 11/24/2025 f1_keywords: - "using_CSharpKeyword" - "using-static_CSharpKeyword" @@ -88,7 +88,7 @@ using static ; The `` is the name of the type whose static members and nested types can be referenced without specifying a type name. If you don't provide a fully qualified type name (the full namespace name along with the type name), C# generates compiler error [CS0246](../compiler-messages/assembly-references.md): "The type or namespace name 'type/namespace' couldn't be found (are you missing a using directive or an assembly reference?)". -If the `using static` directive is applied within the context of a namespace (either file-scoped or nested in a `namespace` block, it is not necessary to fully qualify the type. +If the `using static` directive is applied within the context of a namespace (either file-scoped or nested in a `namespace` block, it isn't necessary to fully qualify the type. The `using static` directive applies to any type that has static members (or nested types), even if it also has instance members. However, instance members can only be invoked through the type instance. @@ -116,7 +116,7 @@ By eliminating the need to explicitly reference the class eac `using static` imports only accessible static members and nested types declared in the specified type. Inherited members aren't imported. You can import from any named type with a `using static` directive, including Visual Basic modules. If F# top-level functions appear in metadata as static members of a named type whose name is a valid C# identifier, then the F# functions can be imported. -`using static` makes extension methods declared in the specified type available for extension method lookup. However, the names of the extension methods aren't imported into scope for unqualified reference in code. +`using static` makes extension members declared in the specified type available for extension member lookup. However, the names of the extension members aren't imported into scope for unqualified reference in code. Methods with the same name imported from different types by different `using static` directives in the same compilation unit or namespace form a method group. Overload resolution within these method groups follows normal C# rules. diff --git a/docs/csharp/language-reference/keywords/where-generic-type-constraint.md b/docs/csharp/language-reference/keywords/where-generic-type-constraint.md index 6e81ba5502889..41d6398125641 100644 --- a/docs/csharp/language-reference/keywords/where-generic-type-constraint.md +++ b/docs/csharp/language-reference/keywords/where-generic-type-constraint.md @@ -2,7 +2,7 @@ description: "where (generic type constraint) - C# Reference" title: "where (generic type constraint)" -ms.date: 07/26/2024 +ms.date: 11/24/2024 f1_keywords: - "whereconstraint" - "whereconstraint_CSharpKeyword" @@ -47,7 +47,7 @@ You use the `default` constraint to specify that your derived class overrides th :::code language="csharp" source="snippets/GenericWhereConstraints.cs" ID="DerivedClass"::: > [!IMPORTANT] -> Generic declarations that include the `notnull` constraint can be used in a nullable oblivious context, but compiler does not enforce the constraint. +> Generic declarations that include the `notnull` constraint can be used in a nullable oblivious context, but compiler doesn't enforce the constraint. :::code language="csharp" source="snippets/GenericWhereConstraints.cs" ID="NotNull"::: diff --git a/docs/csharp/language-reference/operators/deconstruction.md b/docs/csharp/language-reference/operators/deconstruction.md index 989c27a6bce9b..6f0f812396e06 100644 --- a/docs/csharp/language-reference/operators/deconstruction.md +++ b/docs/csharp/language-reference/operators/deconstruction.md @@ -1,7 +1,7 @@ --- title: "Deconstruction expression - extract properties or fields from a tuple or other type" description: "Learn about deconstruction expressions: expressions that extract individual properties or fields from a tuple or user defined type into discrete expressions." -ms.date: 12/17/2024 +ms.date: 11/24/2025 --- # Deconstruction expression - Extract properties of fields from a tuple or other user-defined type @@ -37,7 +37,7 @@ You can make use of this behavior to specify which properties of your record typ ## Declare `Deconstruct` methods -You can add deconstruction support to any class, struct, or interface you declare. You declare one or more `Deconstruct` methods in your type, or as extension methods on that type. A deconstruction expression calls a method `void Deconstruct(out var p1, ..., out var pn)`. The `Deconstruct` method can be either an instance method or an extension method. The type of each parameter in the `Deconstruct` method must match the type of the corresponding argument in the deconstruction expression. The deconstruction expression assigns the value of each argument to the value of the corresponding `out` parameter in the `Deconstruct` method. If multiple `Deconstruct` methods match the deconstruction expression, the compiler reports an error for the ambiguity. +You can add deconstruction support to any class, struct, or interface you declare. You declare one or more `Deconstruct` methods in your type, or as extension on that type. A deconstruction expression calls a method `void Deconstruct(out var p1, ..., out var pn)`. The `Deconstruct` method can be either an instance method or an extension method. The type of each parameter in the `Deconstruct` method must match the type of the corresponding argument in the deconstruction expression. The deconstruction expression assigns the value of each argument to the value of the corresponding `out` parameter in the `Deconstruct` method. If multiple `Deconstruct` methods match the deconstruction expression, the compiler reports an error for the ambiguity. The following code declares a `Point3D` struct that has two `Deconstruct` methods: diff --git a/docs/csharp/language-reference/operators/member-access-operators.md b/docs/csharp/language-reference/operators/member-access-operators.md index 9dda13cf2fd61..5ae030ea32f5c 100644 --- a/docs/csharp/language-reference/operators/member-access-operators.md +++ b/docs/csharp/language-reference/operators/member-access-operators.md @@ -1,7 +1,7 @@ --- title: "Member access and null-conditional operators and expressions:" description: "C# operators that you use to access type members or null-conditionally access type members. These operators include the dot operator - `.`, indexers - `[`, `]`, `^` and `..`, and invocation - `(`, `)`." -ms.date: 05/29/2025 +ms.date: 11/24/2025 author: pkulikov f1_keywords: - "._CSharpKeyword" @@ -62,7 +62,7 @@ You use the `.` token to access a member of a namespace or a type, as the follow :::code language="csharp" source="snippets/shared/MemberAccessOperators.cs" id="TypeMemberAccess" interactive="try-dotnet-method"::: -You can also use `.` to access an [extension method](../../programming-guide/classes-and-structs/extension-methods.md). +You can also use `.` to access an [extension member](../../programming-guide/classes-and-structs/extension-methods.md). ## Indexer operator [] diff --git a/docs/csharp/language-reference/statements/iteration-statements.md b/docs/csharp/language-reference/statements/iteration-statements.md index ebb4f882894b0..0da59b3abb0d9 100644 --- a/docs/csharp/language-reference/statements/iteration-statements.md +++ b/docs/csharp/language-reference/statements/iteration-statements.md @@ -83,7 +83,7 @@ The `foreach` statement executes a statement or a block of statements for each e The `foreach` statement isn't limited to those types. You can use it with an instance of any type that satisfies the following conditions: -- A type has the public parameterless `GetEnumerator` method. The `GetEnumerator` method can be a type's [extension method](../../programming-guide/classes-and-structs/extension-methods.md). +- A type has the public parameterless `GetEnumerator` method. The `GetEnumerator` method can be an [extension method](../../programming-guide/classes-and-structs/extension-methods.md). - The return type of the `GetEnumerator` method has the public `Current` property and the public parameterless `MoveNext` method whose return type is `bool`. The following example uses the `foreach` statement with an instance of the type, which doesn't implement any interfaces: @@ -98,13 +98,13 @@ If the source collection of the `foreach` statement is empty, the body of the `f ### await foreach -You can use the `await foreach` statement to consume an asynchronous stream of data, that is, the collection type that implements the interface. Each iteration of the loop may be suspended while the next element is retrieved asynchronously. The following example shows how to use the `await foreach` statement: +You can use the `await foreach` statement to consume an asynchronous stream of data, that is, the collection type that implements the interface. Each iteration of the loop can be suspended while the next element is retrieved asynchronously. The following example shows how to use the `await foreach` statement: :::code language="csharp" source="snippets/iteration-statements/ForeachStatement.cs" id="AwaitForeach" ::: You can also use the `await foreach` statement with an instance of any type that satisfies the following conditions: -- A type has the public parameterless `GetAsyncEnumerator` method. That method can be a type's [extension method](../../programming-guide/classes-and-structs/extension-methods.md). +- A type has the public parameterless `GetAsyncEnumerator` method. That method can be an [extension member](../../programming-guide/classes-and-structs/extension-methods.md). - The return type of the `GetAsyncEnumerator` method has the public `Current` property and the public parameterless `MoveNextAsync` method whose return type is [`Task`](xref:System.Threading.Tasks.Task%601), [`ValueTask`](xref:System.Threading.Tasks.ValueTask%601), or any other awaitable type whose awaiter's `GetResult` method returns a `bool` value. By default, stream elements are processed in the captured context. If you want to disable capturing of the context, use the extension method. For more information about synchronization contexts and capturing the current context, see [Consuming the Task-based asynchronous pattern](../../../standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md). For more information about asynchronous streams, see the [Asynchronous streams tutorial](../../asynchronous-programming/generate-consume-asynchronous-stream.md). @@ -118,8 +118,8 @@ foreach (var item in collection) { } ``` > [!NOTE] -> Type of `var` can be inferred by the compiler as a nullable reference type, depending on whether the [nullable aware context](../../language-reference/builtin-types/nullable-reference-types.md) is enabled and whether the type of an initialization expression is a reference type. -> For more information see [Implicitly-typed local variables](./declarations.md#implicitly-typed-local-variables). +> The type of a `var` declaration can be inferred by the compiler as a nullable reference type, depending on whether the [nullable aware context](../../language-reference/builtin-types/nullable-reference-types.md) is enabled and whether the type of an initialization expression is a reference type. +> For more information, see [Implicitly-typed local variables](./declarations.md#implicitly-typed-local-variables). You can also explicitly specify the type of an iteration variable, as the following code shows: @@ -128,7 +128,7 @@ IEnumerable collection = new T[5]; foreach (V item in collection) { } ``` -In the preceding form, type `T` of a collection element must be implicitly or explicitly convertible to type `V` of an iteration variable. If an explicit conversion from `T` to `V` fails at run time, the `foreach` statement throws an . For example, if `T` is a non-sealed class type, `V` can be any interface type, even the one that `T` doesn't implement. At run time, the type of a collection element may be the one that derives from `T` and actually implements `V`. If that's not the case, an is thrown. +In the preceding form, type `T` of a collection element must be implicitly or explicitly convertible to type `V` of an iteration variable. If an explicit conversion from `T` to `V` fails at run time, the `foreach` statement throws an . For example, if `T` is a non-sealed class type, `V` can be any interface type, even the one that `T` doesn't implement. At run time, the type of a collection element can be the one that derives from `T` and actually implements `V`. If that's not the case, an is thrown. ## The `do` statement diff --git a/docs/csharp/language-reference/statements/yield.md b/docs/csharp/language-reference/statements/yield.md index 83e4d4524c2b1..f9f3894df5515 100644 --- a/docs/csharp/language-reference/statements/yield.md +++ b/docs/csharp/language-reference/statements/yield.md @@ -1,7 +1,7 @@ --- title: "yield statement - provide the next element in an iterator" description: "Use the yield statement in iterators to provide the next value or signal the end of an iteration" -ms.date: 06/28/2024 +ms.date: 11/24/2025 f1_keywords: - "yield" - "yield_CSharpKeyword" @@ -38,7 +38,7 @@ You can't use the `yield` statements in: - methods with [in](../keywords/method-parameters.md#in-parameter-modifier), [ref](../keywords/ref.md), or [out](../keywords/method-parameters.md#out-parameter-modifier) parameters. - [lambda expressions](../operators/lambda-expressions.md) and [anonymous methods](../operators/delegate-operator.md). - [unsafe blocks](../keywords/unsafe.md). Before C# 13, `yield` was invalid in any method with an `unsafe` block. Beginning with C# 13, you can use `yield` in methods with `unsafe` blocks, but not in the `unsafe` block. -- `yield return` and `yield break` can not be used in [catch](../statements/exception-handling-statements.md) and [finally](../statements/exception-handling-statements.md) blocks, or in [try](../statements/exception-handling-statements.md) blocks with a corresponding `catch` block. The `yield return` and `yield break` statements can be used in a `try` block with no `catch` blocks, only a `finally` block. +- `yield return` and `yield break` can't be used in [catch](../statements/exception-handling-statements.md) and [finally](../statements/exception-handling-statements.md) blocks, or in [try](../statements/exception-handling-statements.md) blocks with a corresponding `catch` block. The `yield return` and `yield break` statements can be used in a `try` block with no `catch` blocks, only a `finally` block. ## `using` statements in iterators diff --git a/docs/csharp/language-reference/toc.yml b/docs/csharp/language-reference/toc.yml index c183361da12fd..800bc43316d71 100644 --- a/docs/csharp/language-reference/toc.yml +++ b/docs/csharp/language-reference/toc.yml @@ -526,20 +526,26 @@ items: href: ./compiler-messages/interface-implementation-errors.md displayName: > interface, - CS0071, CS0106, CS0277, CS0425, CS0460, CS0470, CS0473, CS0531, CS0535, CS0538, CS0539, CS0540, - CS0541, CS0550, CS0551, CS0630, CS0686, CS0736, CS0737, CS0738, CS8705, CS8707, CS8711, CS8854, - CS9333, CS9334 + CS0071, CS0106, CS0277, CS0425, CS0460, CS0470, CS0473, CS0531, CS0535, CS0538, + CS0539, CS0540, CS0541, CS0550, CS0551, CS0630, CS0686, CS0736, CS0737, CS0738, + CS8705, CS8707, CS8711, CS8854, CS9333, CS9334 - name: Reference parameters href: ./compiler-messages/ref-modifiers-errors.md displayName: > - ref safety, + ref parameters, CS0192, CS0199, CS0206, CS0631, CS0767, CS1510, CS1605, CS1623, CS1649, CS1651, - CS1655, CS1657, CS1741, CS1939, CS1988, CS7084, CS8166, CS8167, CS8168, CS8169, - CS8325, CS8326, CS8327, CS8329, CS8330, CS8331, CS8332, CS8337, CS8338, CS8351, - CS8373, CS8374, CS8388, CS8977, CS9072, CS9077, CS9078, CS9079, CS9085, CS9086, - CS9087, CS9089, CS9091, CS9092, CS9093, CS9094, CS9095, CS9096, CS9097, CS9101, + CS1655, CS1657, CS1741, CS1939, CS1988, CS7084, CS8196, CS8325, CS8326, CS8327, + CS8329, CS8330, CS8331, CS8332, CS8337, CS8338, CS8373, CS8388, CS8977, CS8986, + CS8987, CS9061, CS9062, CS9063, CS9065, CS9066, CS9072, CS9073, CS9074, CS9101, CS9102, CS9104, CS9190, CS9191, CS9192, CS9193, CS9195, CS9196, CS9197, CS9198, CS9199, CS9200, CS9201, CS9205, CS9265 + - name: Ref safety + href: ./compiler-messages/ref-safety-errors.md + displayName: > + ref safety, + CS8166, CS8167, CS8168, CS8169, CS8345, CS8351, CS8374, CS9075, CS9076, CS9077, + CS9078, CS9079, CS9080, CS9081, CS9082, CS9083, CS9084, CS9085, CS9086, CS9087, + CS9088, CS9089, CS9090, CS9091, CS9092, CS9093, CS9094, CS9095, CS9096, CS9097 - name: "`ref struct` types" href: ./compiler-messages/ref-struct-errors.md displayName: > diff --git a/docs/csharp/methods.md b/docs/csharp/methods.md index c080032bf08c6..e77e7b50be77b 100644 --- a/docs/csharp/methods.md +++ b/docs/csharp/methods.md @@ -211,7 +211,7 @@ If a method takes an array as a parameter and modifies the value of individual e :::code language="csharp" source="snippets/methods/returnarray1.cs" id="snippet101"::: -## Extension methods +## Extension members Ordinarily, there are two ways to add a method to an existing type: diff --git a/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md b/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md index 15c2303696612..1d541b82007d3 100644 --- a/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md +++ b/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md @@ -459,8 +459,6 @@ f1_keywords: - "CS8980" - "CS8984" - "CS8985" - - "CS8986" - - "CS8987" - "CS8989" - "CS9011" - "CS9012" @@ -495,43 +493,13 @@ f1_keywords: - "CS9053" - "CS9054" - "CS9056" - - "CS9057" + - "CS9058" - "CS9060" - - "CS9061" - - "CS9062" - - "CS9063" - - "CS9065" - - "CS9066" + - "CS9064" - "CS9067" - "CS9068" - - "CS9069" - "CS9070" - "CS9071" - - "CS9073" - - "CS9074" - - "CS9075" - - "CS9076" - - "CS9077" - - "CS9078" - - "CS9079" - - "CS9080" - - "CS9081" - - "CS9082" - - "CS9083" - - "CS9084" - - "CS9085" - - "CS9086" - - "CS9087" - - "CS9088" - - "CS9089" - - "CS9090" - - "CS9091" - - "CS9092" - - "CS9093" - - "CS9094" - - "CS9095" - - "CS9096" - - "CS9097" helpviewer_keywords: - "errors [C#], additional information" --- diff --git a/docs/csharp/roslyn-sdk/get-started/syntax-transformation.md b/docs/csharp/roslyn-sdk/get-started/syntax-transformation.md index 5eca2838d8f9f..f6fdf6761a23f 100644 --- a/docs/csharp/roslyn-sdk/get-started/syntax-transformation.md +++ b/docs/csharp/roslyn-sdk/get-started/syntax-transformation.md @@ -57,7 +57,7 @@ Run the program again to see that you've built the tree for the code to add. ### Create a modified tree -You've built a small syntax tree that contains one statement. The APIs to create new nodes are the right choice to create single statements or other small code blocks. However, to build larger blocks of code, you should use methods that replace nodes or insert nodes into an existing tree. Remember that syntax trees are immutable. The **Syntax API** doesn't provide any mechanism for modifying an existing syntax tree after construction. Instead, it provides methods that produce new trees based on changes to existing ones. `With*` methods are defined in concrete classes that derive from or in extension methods declared in the class. These methods create a new node by applying changes to an existing node's child properties. Additionally, the extension method can be used to replace a descendent node in a subtree. This method also updates the parent to point to the newly created child and repeats this process up the entire tree - a process known as _re-spinning_ the tree. +You've built a small syntax tree that contains one statement. The APIs to create new nodes are the right choice to create single statements or other small code blocks. However, to build larger blocks of code, you should use methods that replace nodes or insert nodes into an existing tree. Remember that syntax trees are immutable. The **Syntax API** doesn't provide any mechanism for modifying an existing syntax tree after construction. Instead, it provides methods that produce new trees based on changes to existing ones. `With*` methods are defined in concrete classes that derive from or in extension members declared in the class. These methods create a new node by applying changes to an existing node's child properties. Additionally, the extension member can be used to replace a descendent node in a subtree. This method also updates the parent to point to the newly created child and repeats this process up the entire tree - a process known as _re-spinning_ the tree. The next step is to create a tree that represents an entire (small) program and then modify it. Add the following code to the beginning of the `Program` class: diff --git a/docs/csharp/roslyn-sdk/tutorials/how-to-write-csharp-analyzer-code-fix.md b/docs/csharp/roslyn-sdk/tutorials/how-to-write-csharp-analyzer-code-fix.md index 73f8d4ac449c8..f273ff10e457b 100644 --- a/docs/csharp/roslyn-sdk/tutorials/how-to-write-csharp-analyzer-code-fix.md +++ b/docs/csharp/roslyn-sdk/tutorials/how-to-write-csharp-analyzer-code-fix.md @@ -148,7 +148,7 @@ This cast always succeeds because your analyzer registered for changes to local Finally, you need to check that the variable could be `const`. That means making sure it is never assigned after it is initialized. -You'll perform some semantic analysis using the . You use the `context` argument to determine whether the local variable declaration can be made `const`. A represents all of semantic information in a single source file. You can learn more in the article that covers [semantic models](../work-with-semantics.md). You'll use the to perform data flow analysis on the local declaration statement. Then, you use the results of this data flow analysis to ensure that the local variable isn't written with a new value anywhere else. Call the extension method to retrieve the for the variable and check that it isn't contained with the collection of the data flow analysis. Add the following code to the end of the `AnalyzeNode` method: +You'll perform some semantic analysis using the . You use the `context` argument to determine whether the local variable declaration can be made `const`. A represents all of semantic information in a single source file. You can learn more in the article that covers [semantic models](../work-with-semantics.md). You'll use the to perform data flow analysis on the local declaration statement. Then, you use the results of this data flow analysis to ensure that the local variable isn't written with a new value anywhere else. Call the extension member to retrieve the for the variable and check that it isn't contained with the collection of the data flow analysis. Add the following code to the end of the `AnalyzeNode` method: ```csharp // Perform data flow analysis on the local declaration. diff --git a/docs/csharp/whats-new/csharp-14.md b/docs/csharp/whats-new/csharp-14.md index f982c1978c7b4..5a4261fd6edfa 100644 --- a/docs/csharp/whats-new/csharp-14.md +++ b/docs/csharp/whats-new/csharp-14.md @@ -17,6 +17,7 @@ C# 14 includes the following new features. You can try these features using the - [`field` backed properties](#the-field-keyword) - [`partial` events and constructors](#more-partial-members) - [user-defined compound assignment operators](#user-defined-compound-assignment) +- [new preprocessor directives for File-based apps](../language-reference/preprocessor-directives.md#file-based-apps) C# 14 is the latest C# release. C# 14 is supported on **.NET 10**. For more information, see [C# language versioning](../language-reference/configure-language-version.md). diff --git a/docs/framework/app-domains/how-to-remove-an-assembly-from-the-gac.md b/docs/framework/app-domains/how-to-remove-an-assembly-from-the-gac.md index 0acec88cc70c3..80a24325bb0ec 100644 --- a/docs/framework/app-domains/how-to-remove-an-assembly-from-the-gac.md +++ b/docs/framework/app-domains/how-to-remove-an-assembly-from-the-gac.md @@ -27,7 +27,7 @@ There are two ways to remove an assembly from the global assembly cache (GAC): At the command prompt, type the following command: -**gacutil –u** \<*assembly name*> +**gacutil -u** \<*assembly name*> In this command, *assembly name* is the name of the assembly to remove from the global assembly cache. diff --git a/docs/framework/configure-apps/index.md b/docs/framework/configure-apps/index.md index 319aef51062af..635d54ed5cb6a 100644 --- a/docs/framework/configure-apps/index.md +++ b/docs/framework/configure-apps/index.md @@ -67,7 +67,7 @@ This article describes the syntax of configuration files and provides informatio The name and location of the application configuration file depend on the app's host, which can be one of the following: -- Executable–hosted app. +- Executable-hosted app. These apps have two configuration files: a source configuration file, which is modified by the developer during development, and an output file that's distributed with the app. diff --git a/docs/framework/data/adonet/ef/language-reference/literals-entity-sql.md b/docs/framework/data/adonet/ef/language-reference/literals-entity-sql.md index 5b71bdad17250..65942ebdb5a4e 100644 --- a/docs/framework/data/adonet/ef/language-reference/literals-entity-sql.md +++ b/docs/framework/data/adonet/ef/language-reference/literals-entity-sql.md @@ -94,7 +94,7 @@ DATETIMEOFFSET'2006-12-25 01:01:00.0000000 -08:30' Binary'00ffaabb' X'ABCabc' BINARY '0f0f0f0F0F0F0F0F0F0F' -X'' –- empty binary string +X'' -- empty binary string ``` ## Guid diff --git a/docs/framework/data/adonet/sql/linq/system-datetime-methods.md b/docs/framework/data/adonet/sql/linq/system-datetime-methods.md index 8455d7718642b..cc82e190ec5d2 100644 --- a/docs/framework/data/adonet/sql/linq/system-datetime-methods.md +++ b/docs/framework/data/adonet/sql/linq/system-datetime-methods.md @@ -6,29 +6,29 @@ ms.assetid: 4f80700c-e83f-4ab6-af0f-1c9a606e1133 --- # System.DateTime Methods -The following LINQ to SQL-supported methods, operators, and properties are available to use in LINQ to SQL queries. When a method, operator or property is unsupported, LINQ to SQL cannot translate the member for execution on the SQL Server. You may use these members in your code, however, they must be evaluated before the query is translated to Transact-SQL or after the results have been retrieved from the database. - -## Supported System.DateTime Members - - Once mapped in the object model or external mapping file, LINQ to SQL allows you to call the following members inside LINQ to SQL queries. - -|Supported Methods|Supported Operators|Supported Properties| -|-|-|-| -|||| -|||| -|||| -|||| -|||| -|||| -|||| -|||| -|||| -|||| -|||| -|||| -|||| - -## Members Not Supported by LINQ to SQL +The following LINQ to SQL-supported methods, operators, and properties are available to use in LINQ to SQL queries. When a method, operator or property is unsupported, LINQ to SQL cannot translate the member for execution on the SQL Server. You may use these members in your code, however, they must be evaluated before the query is translated to Transact-SQL or after the results have been retrieved from the database. + +## Supported System.DateTime Members + + Once mapped in the object model or external mapping file, LINQ to SQL allows you to call the following members inside LINQ to SQL queries. + +|Supported Methods|Supported Operators|Supported Properties| +|-|-|-| +|||| +|||| +|||| +|||| +|||| +|||| +|||| +|||| +|||| +|||| +|||| +|||| +|||| + +## Members Not Supported by LINQ to SQL The following members are not supported inside LINQ to SQL queries: @@ -50,18 +50,18 @@ The following LINQ to SQL-supported methods, operators, and properties are avail - - - - -## Method Translation Example - - All methods supported by LINQ to SQL are translated to Transact-SQL before they are sent to SQL Server. For example, consider the following pattern. - - `(dateTime1 – dateTime2).{Days, Hours, Milliseconds, Minutes, Months, Seconds, Years}` - - When it is recognized, it is translated into a direct call to the SQL Server `DATEDIFF` function, as follows: - - `DATEDIFF({DatePart}, @dateTime1, @dateTime2)` - -## SQLMethods Date and Time Methods + +## Method Translation Example + + All methods supported by LINQ to SQL are translated to Transact-SQL before they are sent to SQL Server. For example, consider the following pattern. + + `(dateTime1 - dateTime2).{Days, Hours, Milliseconds, Minutes, Months, Seconds, Years}` + + When it is recognized, it is translated into a direct call to the SQL Server `DATEDIFF` function, as follows: + + `DATEDIFF({DatePart}, @dateTime1, @dateTime2)` + +## SQLMethods Date and Time Methods In addition to the methods offered by the structure, LINQ to SQL offers the following methods from the class for working with date and time: @@ -74,7 +74,7 @@ The following LINQ to SQL-supported methods, operators, and properties are avail - - - - + ## See also - [Query Concepts](query-concepts.md) diff --git a/docs/framework/interop/com-interop-sample-com-client-and-net-server.md b/docs/framework/interop/com-interop-sample-com-client-and-net-server.md index 9f95163695e7d..f1a497f7fd3f9 100644 --- a/docs/framework/interop/com-interop-sample-com-client-and-net-server.md +++ b/docs/framework/interop/com-interop-sample-com-client-and-net-server.md @@ -2,389 +2,389 @@ title: "COM Interop Sample: COM Client and .NET Server" description: Read a code sample that shows the interoperation of a COM client and a .NET server that performs mortgage calculations. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "interoperation with unmanaged code, samples" - "COM interop, samples" ms.assetid: a219cb2c-9fa2-4c90-9b26-939e0788f178 --- # COM Interop Sample: COM Client and .NET Server -This sample demonstrates the interoperation of a [COM Client](#cpconcominteropsamplecomclientnetserveranchor1) and a [.NET Server](#cpconcominteropsamplecomclientnetserveranchor2) that performs mortgage calculations. In this example, the client creates and calls an instance of the managed `Loan` class, passes four arguments (one of those four being equal to zero) to the instance, and displays the computations. Code examples from this sample appear throughout this section. - +This sample demonstrates the interoperation of a [COM Client](#cpconcominteropsamplecomclientnetserveranchor1) and a [.NET Server](#cpconcominteropsamplecomclientnetserveranchor2) that performs mortgage calculations. In this example, the client creates and calls an instance of the managed `Loan` class, passes four arguments (one of those four being equal to zero) to the instance, and displays the computations. Code examples from this sample appear throughout this section. + -## COM Client - -```cpp -// ConLoan.cpp : Defines the entry point for the console application. -#include "stdafx.h" -#import "..\LoanLib\LoanLib.tlb" raw_interfaces_only -using namespace LoanLib; - -int main(int argc, char* argv[]) -{ - HRESULT hr = CoInitialize(NULL); - - ILoanPtr pILoan(__uuidof(Loan)); - +## COM Client + +```cpp +// ConLoan.cpp : Defines the entry point for the console application. +#include "stdafx.h" +#import "..\LoanLib\LoanLib.tlb" raw_interfaces_only +using namespace LoanLib; + +int main(int argc, char* argv[]) +{ + HRESULT hr = CoInitialize(NULL); + + ILoanPtr pILoan(__uuidof(Loan)); + if (argc < 5) - { - printf("Usage: ConLoan Balance Rate Term Payment\n"); - printf(" Either Balance, Rate, Term, or Payment must be 0\n"); - return -1; - } - - double openingBalance = atof(argv[1]); - double rate = atof(argv[2])/100.0; - short term = atoi(argv[3]); - double payment = atof(argv[4]); - - pILoan->put_OpeningBalance(openingBalance); - pILoan->put_Rate(rate); - pILoan->put_Term(term); - pILoan->put_Payment(payment); - + { + printf("Usage: ConLoan Balance Rate Term Payment\n"); + printf(" Either Balance, Rate, Term, or Payment must be 0\n"); + return -1; + } + + double openingBalance = atof(argv[1]); + double rate = atof(argv[2])/100.0; + short term = atoi(argv[3]); + double payment = atof(argv[4]); + + pILoan->put_OpeningBalance(openingBalance); + pILoan->put_Rate(rate); + pILoan->put_Term(term); + pILoan->put_Payment(payment); + if (openingBalance == 0.00) - pILoan->ComputeOpeningBalance(&openingBalance); - if (rate == 0.00) pILoan->ComputeRate(&rate); - if (term == 0) pILoan->ComputeTerm(&term); - if (payment == 0.00) pILoan->ComputePayment(&payment); - - printf("Balance = %.2f\n", openingBalance); - printf("Rate = %.1f%%\n", rate*100); - printf("Term = %.2i\n", term); - printf("Payment = %.2f\n", payment); - - VARIANT_BOOL MorePmts; - double Balance = 0.0; - double Principal = 0.0; - double Interest = 0.0; - - printf("%4s%10s%12s%10s%12s\n", "Nbr", "Payment", "Principal", "Interest", "Balance"); + pILoan->ComputeOpeningBalance(&openingBalance); + if (rate == 0.00) pILoan->ComputeRate(&rate); + if (term == 0) pILoan->ComputeTerm(&term); + if (payment == 0.00) pILoan->ComputePayment(&payment); + + printf("Balance = %.2f\n", openingBalance); + printf("Rate = %.1f%%\n", rate*100); + printf("Term = %.2i\n", term); + printf("Payment = %.2f\n", payment); + + VARIANT_BOOL MorePmts; + double Balance = 0.0; + double Principal = 0.0; + double Interest = 0.0; + + printf("%4s%10s%12s%10s%12s\n", "Nbr", "Payment", "Principal", "Interest", "Balance"); printf("%4s%10s%12s%10s%12s\n", "---", "-------", "---------", -"--------", "-------"); - - pILoan->GetFirstPmtDistribution(payment, &Balance, &Principal, &Interest, &MorePmts); - +"--------", "-------"); + + pILoan->GetFirstPmtDistribution(payment, &Balance, &Principal, &Interest, &MorePmts); + for (short PmtNbr = 1; MorePmts; PmtNbr++) - { - printf("%4i%10.2f%12.2f%10.2f%12.2f\n", - PmtNbr, payment, Principal, Interest, Balance); - + { + printf("%4i%10.2f%12.2f%10.2f%12.2f\n", + PmtNbr, payment, Principal, Interest, Balance); + pILoan->GetNextPmtDistribution(payment, &Balance, &Principal, &Interest, &MorePmts); - } - - CoUninitialize(); - return 0; -} -``` - + } + + CoUninitialize(); + return 0; +} +``` + -## .NET Server - -```vb -Imports System -Imports System.Reflection - - +## .NET Server + +```vb +Imports System +Imports System.Reflection + + Namespace LoanLib - + Public Interface ILoan - Property OpeningBalance() As Double + Property OpeningBalance() As Double Property Rate() As Double Property Payment() As Double Property Term() As Short - Property RiskRating() As String - Function ComputePayment() As Double - Function ComputeOpeningBalance() As Double - Function ComputeRate() As Double - Function ComputeTerm() As Short - Function GetFirstPmtDistribution(PmtAmt As Double, _ - ByRef Balance As Double, ByRef PrinPortion As Double, _ - ByRef IntPortion As Double) As Boolean - Function GetNextPmtDistribution(PmtAmt As Double, _ - ByRef Balance As Double, ByRef PrinPortion As Double, _ - ByRef IntPortion As Double) As Boolean + Property RiskRating() As String + Function ComputePayment() As Double + Function ComputeOpeningBalance() As Double + Function ComputeRate() As Double + Function ComputeTerm() As Short + Function GetFirstPmtDistribution(PmtAmt As Double, _ + ByRef Balance As Double, ByRef PrinPortion As Double, _ + ByRef IntPortion As Double) As Boolean + Function GetNextPmtDistribution(PmtAmt As Double, _ + ByRef Balance As Double, ByRef PrinPortion As Double, _ + ByRef IntPortion As Double) As Boolean End Interface - - Public Class Loan - Implements ILoan - Private m_openingBalance As Double - Private m_rate As Double - Private m_payment As Double - Private m_term As Short + + Public Class Loan + Implements ILoan + Private m_openingBalance As Double + Private m_rate As Double + Private m_payment As Double + Private m_term As Short Private m_riskRating As String - - Public Property OpeningBalance() As Double _ - Implements ILoan.OpeningBalance - - Get - Return m_openingBalance - End Get - Set - m_openingBalance = value - End Set + + Public Property OpeningBalance() As Double _ + Implements ILoan.OpeningBalance + + Get + Return m_openingBalance + End Get + Set + m_openingBalance = value + End Set + End Property + + Public Property Rate() As Double _ + Implements ILoan.Rate + + Get + Return m_rate + End Get + Set + m_rate = value + End Set End Property - - Public Property Rate() As Double _ - Implements ILoan.Rate - - Get - Return m_rate - End Get - Set - m_rate = value - End Set + + Public Property Payment() As Double _ + Implements ILoan.Payment + + Get + Return m_payment + End Get + Set + m_payment = value + End Set End Property - - Public Property Payment() As Double _ - Implements ILoan.Payment - - Get - Return m_payment - End Get - Set - m_payment = value - End Set + + Public Property Term() As Short _ + Implements ILoan.Term + + Get + Return m_term + End Get + Set + m_term = value + End Set End Property - - Public Property Term() As Short _ - Implements ILoan.Term - - Get - Return m_term - End Get - Set - m_term = value - End Set + + Public Property RiskRating() As String _ + Implements ILoan.RiskRating + + Get + Return m_riskRating + End Get + Set + m_riskRating = value + End Set End Property - - Public Property RiskRating() As String _ - Implements ILoan.RiskRating - - Get - Return m_riskRating - End Get - Set - m_riskRating = value - End Set - End Property - - Public Function ComputePayment() As Double _ - Implements ILoan.ComputePayment - - Payment = Util.Round(OpeningBalance *(Rate / _ - (1 - Math.Pow(1 + Rate, - Term))), 2) - Return Payment + + Public Function ComputePayment() As Double _ + Implements ILoan.ComputePayment + + Payment = Util.Round(OpeningBalance *(Rate / _ + (1 - Math.Pow(1 + Rate, - Term))), 2) + Return Payment End Function - - Public Function ComputeOpeningBalance() As Double _ - Implements ILoan.ComputeOpeningBalance - - OpeningBalance = Util.Round(Payment /(Rate / _ - (1 - Math.Pow(1 + Rate, - Term))), 2) - Return OpeningBalance + + Public Function ComputeOpeningBalance() As Double _ + Implements ILoan.ComputeOpeningBalance + + OpeningBalance = Util.Round(Payment /(Rate / _ + (1 - Math.Pow(1 + Rate, - Term))), 2) + Return OpeningBalance End Function - - Public Function ComputeRate() As Double _ - Implements ILoan.ComputeRate - - Dim DesiredPayment As Double = Payment - - For m_rate = 0.001 To 28.0 - 0.001 Step 0.001 - Payment = Util.Round(OpeningBalance *(Rate / _ - (1 - Math.Pow(1 + Rate, - Term))), 2) - - If Payment >= DesiredPayment Then - Exit For - End If - Next - Return Rate + + Public Function ComputeRate() As Double _ + Implements ILoan.ComputeRate + + Dim DesiredPayment As Double = Payment + + For m_rate = 0.001 To 28.0 - 0.001 Step 0.001 + Payment = Util.Round(OpeningBalance *(Rate / _ + (1 - Math.Pow(1 + Rate, - Term))), 2) + + If Payment >= DesiredPayment Then + Exit For + End If + Next + Return Rate End Function - - Public Function ComputeTerm() As Short _ - Implements ILoan.ComputeTerm - - Dim DesiredPayment As Double = Payment - - For m_term = 1 To 479 - Payment = Util.Round(OpeningBalance *(Rate / _ - (1 - Math.Pow(1 + Rate, - Term))), 2) - - If Payment <= DesiredPayment Then - Exit For - End If - Next - Return Term + + Public Function ComputeTerm() As Short _ + Implements ILoan.ComputeTerm + + Dim DesiredPayment As Double = Payment + + For m_term = 1 To 479 + Payment = Util.Round(OpeningBalance *(Rate / _ + (1 - Math.Pow(1 + Rate, - Term))), 2) + + If Payment <= DesiredPayment Then + Exit For + End If + Next + Return Term End Function - - Public Function GetFirstPmtDistribution(PmtAmt As Double, _ - ByRef Balance As Double, ByRef PrinPortion As Double, _ - ByRef IntPortion As Double) As Boolean _ - Implements ILoan.GetFirstPmtDistribution - - Balance = OpeningBalance - Return GetNextPmtDistribution(PmtAmt, Balance, PrinPortion, _ - IntPortion) + + Public Function GetFirstPmtDistribution(PmtAmt As Double, _ + ByRef Balance As Double, ByRef PrinPortion As Double, _ + ByRef IntPortion As Double) As Boolean _ + Implements ILoan.GetFirstPmtDistribution + + Balance = OpeningBalance + Return GetNextPmtDistribution(PmtAmt, Balance, PrinPortion, _ + IntPortion) End Function - - Public Function GetNextPmtDistribution(PmtAmt As Double, _ - ByRef Balance As Double, ByRef PrinPortion As Double, _ - ByRef IntPortion As Double) As Boolean _ - Implements ILoan.GetNextPmtDistribution - - IntPortion = Util.Round(Balance * Rate, 2) - PrinPortion = Util.Round(PmtAmt - IntPortion, 2) - Balance = Util.Round(Balance - PrinPortion, 2) - - If Balance <= 0.0 Then - Return False + + Public Function GetNextPmtDistribution(PmtAmt As Double, _ + ByRef Balance As Double, ByRef PrinPortion As Double, _ + ByRef IntPortion As Double) As Boolean _ + Implements ILoan.GetNextPmtDistribution + + IntPortion = Util.Round(Balance * Rate, 2) + PrinPortion = Util.Round(PmtAmt - IntPortion, 2) + Balance = Util.Round(Balance - PrinPortion, 2) + + If Balance <= 0.0 Then + Return False End If - Return True - End Function + Return True + End Function + End Class + + Friend Class Util + + Public Shared Function Round(value As Double, digits As Short) _ + As Double + Dim factor As Double = Math.Pow(10, digits) + Return Math.Round((value * factor)) / factor + End Function + End Class - - Friend Class Util - - Public Shared Function Round(value As Double, digits As Short) _ - As Double - Dim factor As Double = Math.Pow(10, digits) - Return Math.Round((value * factor)) / factor - End Function - - End Class - -End Namespace -``` - -```csharp -using System; -using System.Reflection; - -[assembly:AssemblyKeyFile("sample.snk")] -namespace LoanLib { - - public interface ILoan { - double OpeningBalance{get; set;} - double Rate{get; set;} + +End Namespace +``` + +```csharp +using System; +using System.Reflection; + +[assembly:AssemblyKeyFile("sample.snk")] +namespace LoanLib { + + public interface ILoan { + double OpeningBalance{get; set;} + double Rate{get; set;} double Payment{get; set;} - short Term{get; set;} - String RiskRating{get; set;} - - double ComputePayment(); - double ComputeOpeningBalance(); - double ComputeRate(); - short ComputeTerm(); - bool GetFirstPmtDistribution(double PmtAmt, ref double Balance, - out double PrinPortion, out double IntPortion); - bool GetNextPmtDistribution(double PmtAmt, ref double Balance, - out double PrinPortion, out double IntPortion); - } - - public class Loan : ILoan { - private double openingBalance; - private double rate; - private double payment; - private short term; + short Term{get; set;} + String RiskRating{get; set;} + + double ComputePayment(); + double ComputeOpeningBalance(); + double ComputeRate(); + short ComputeTerm(); + bool GetFirstPmtDistribution(double PmtAmt, ref double Balance, + out double PrinPortion, out double IntPortion); + bool GetNextPmtDistribution(double PmtAmt, ref double Balance, + out double PrinPortion, out double IntPortion); + } + + public class Loan : ILoan { + private double openingBalance; + private double rate; + private double payment; + private short term; private String riskRating; - - public double OpeningBalance { - get { return openingBalance; } - set { openingBalance = value; } - } - - public double Rate { - get { return rate; } - set { rate = value; } - } - - public double Payment { - get { return payment; } - set { payment = value; } - } - - public short Term { - get { return term; } - set { term = value; } - } - - public String RiskRating { - get { return riskRating; } - set { riskRating = value; } - } - - public double ComputePayment() { - Payment = Util.Round(OpeningBalance * (Rate / (1 – - Math.Pow((1 + Rate), -Term))), 2); - return Payment; - } - - public double ComputeOpeningBalance() { + + public double OpeningBalance { + get { return openingBalance; } + set { openingBalance = value; } + } + + public double Rate { + get { return rate; } + set { rate = value; } + } + + public double Payment { + get { return payment; } + set { payment = value; } + } + + public short Term { + get { return term; } + set { term = value; } + } + + public String RiskRating { + get { return riskRating; } + set { riskRating = value; } + } + + public double ComputePayment() { + Payment = Util.Round(OpeningBalance * (Rate / (1 - + Math.Pow((1 + Rate), -Term))), 2); + return Payment; + } + + public double ComputeOpeningBalance() { OpeningBalance = Util.Round(Payment / (Rate / (1 - Math.Pow((1 - + Rate), -Term))), 2); - return OpeningBalance; - } - - public double ComputeRate() { - double DesiredPayment = Payment; - - for (Rate = 0.001; Rate < 28.0; Rate += 0.001) { - Payment = Util.Round(OpeningBalance * (Rate / (1 – - Math.Pow((1 + Rate), -Term))), 2); - - if (Payment >= DesiredPayment) - break; - } + + Rate), -Term))), 2); + return OpeningBalance; + } + + public double ComputeRate() { + double DesiredPayment = Payment; + + for (Rate = 0.001; Rate < 28.0; Rate += 0.001) { + Payment = Util.Round(OpeningBalance * (Rate / (1 - + Math.Pow((1 + Rate), -Term))), 2); + + if (Payment >= DesiredPayment) + break; + } return Rate; - } - - public short ComputeTerm() { - double DesiredPayment = Payment; - - for (Term = 1; Term < 480 ; Term ++) { - Payment = Util.Round(OpeningBalance * (Rate / (1 – - Math.Pow((1 + Rate), -Term))),2); - - if (Payment <= DesiredPayment) - break; - } - + } + + public short ComputeTerm() { + double DesiredPayment = Payment; + + for (Term = 1; Term < 480 ; Term ++) { + Payment = Util.Round(OpeningBalance * (Rate / (1 - + Math.Pow((1 + Rate), -Term))),2); + + if (Payment <= DesiredPayment) + break; + } + return Term; - } - + } + public bool GetFirstPmtDistribution(double PmtAmt, ref double - Balance, out double PrinPortion, out double IntPortion) { - Balance = OpeningBalance; + Balance, out double PrinPortion, out double IntPortion) { + Balance = OpeningBalance; return GetNextPmtDistribution(PmtAmt, ref Balance, out PrinPortion, out IntPortion); - } - + } + public bool GetNextPmtDistribution(double PmtAmt, ref double - Balance, out double PrinPortion, out double IntPortion) { - IntPortion = Util.Round(Balance * Rate, 2); - PrinPortion = Util.Round(PmtAmt - IntPortion,2); - Balance = Util.Round(Balance - PrinPortion,2); - + Balance, out double PrinPortion, out double IntPortion) { + IntPortion = Util.Round(Balance * Rate, 2); + PrinPortion = Util.Round(PmtAmt - IntPortion,2); + Balance = Util.Round(Balance - PrinPortion,2); + if (Balance <= 0.0) - return false; - - return true; - } - } - - internal class Util { - public static double Round(double value, short digits) { - double factor = Math.Pow(10, digits); - return Math.Round(value * factor) / factor; - } - } -} -``` - + return false; + + return true; + } + } + + internal class Util { + public static double Round(double value, short digits) { + double factor = Math.Pow(10, digits); + return Math.Round(value * factor) / factor; + } + } +} +``` + ## See also - [Exposing .NET Framework Components to COM](exposing-dotnet-components-to-com.md) diff --git a/docs/framework/tools/al-exe-assembly-linker.md b/docs/framework/tools/al-exe-assembly-linker.md index e22289e17d474..7737af7307d77 100644 --- a/docs/framework/tools/al-exe-assembly-linker.md +++ b/docs/framework/tools/al-exe-assembly-linker.md @@ -47,7 +47,7 @@ You can specify the following `options`; you must specify **/out**. |**/config[uration]:** `text`|Specifies a string for the Configuration field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If text is an empty string, the Win32 Configuration resource appears as a single space.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/copy[right]:** `text`|Specifies a string for the Copyright field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/copyright** appears in File Explorer as the Win32 Copyright resource.

If text is an empty string, the Win32 Copyright resource appears as a single space.

If you specify **/win32res**, **/copyright** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/c[ulture]:** `text`|Specifies the culture string to associate with the assembly. Valid values for cultures are those defined by the Internet Requests for Comments (RFC) document 1766 titled "Tags for the Identification of Languages."

Place the string in double quotation marks (" ") if `text` contains a space. There is no default culture string. This string is available for viewing with reflection.

For information about valid `text` strings, see the .

You can also specify this option as a custom attribute () in the source code for any CIL module.| -|`/delay[sign][+ or -]`|Specifies whether the assembly will be fully or partially signed. Use **/delaysign-** if you want a fully signed assembly. Use **/delaysign+** if you only want to include the public key in the assembly.

When you request a fully signed assembly, *Al.exe* hashes the file that contains the manifest (assembly metadata) and signs that hash with the private key. The resulting digital signature is stored in the file that contains the manifest. When an assembly is delay signed, *Al.exe* does not compute and store the signature, but just reserves space in the file so the signature can be added later.

The default is **/delaysign-**.

The **/delaysign** option has no effect unless used with **/keyfile** or **/keyname**.

For example, using **/delaysign+** enables a tester to put the assembly in the global cache. After testing, you can fully sign the assembly by including the private key in the assembly.

Note: Before using the [*Gacutil.exe* (Global Assembly Cache Tool)](gacutil-exe-gac-tool.md) to put a delay-signed assembly into the global cache, use the [*Sn.exe* (Strong Name Tool)](sn-exe-strong-name-tool.md) to register the assembly for verification skipping. For example, `Sn.exe –Vr delaySignedAssembly`. Use this only for development.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|`/delay[sign][+ or -]`|Specifies whether the assembly will be fully or partially signed. Use **/delaysign-** if you want a fully signed assembly. Use **/delaysign+** if you only want to include the public key in the assembly.

When you request a fully signed assembly, *Al.exe* hashes the file that contains the manifest (assembly metadata) and signs that hash with the private key. The resulting digital signature is stored in the file that contains the manifest. When an assembly is delay signed, *Al.exe* does not compute and store the signature, but just reserves space in the file so the signature can be added later.

The default is **/delaysign-**.

The **/delaysign** option has no effect unless used with **/keyfile** or **/keyname**.

For example, using **/delaysign+** enables a tester to put the assembly in the global cache. After testing, you can fully sign the assembly by including the private key in the assembly.

Note: Before using the [*Gacutil.exe* (Global Assembly Cache Tool)](gacutil-exe-gac-tool.md) to put a delay-signed assembly into the global cache, use the [*Sn.exe* (Strong Name Tool)](sn-exe-strong-name-tool.md) to register the assembly for verification skipping. For example, `Sn.exe -Vr delaySignedAssembly`. Use this only for development.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/descr[iption]:** `text`|Specifies a string for the field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/description** appears in File Explorer as the Win32 **Comments** resource.

If text is an empty string, the Win32 **Comments** resource appears as a single space.

If you specify **/win32res**, **/description** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/e[vidence]:** `file`|Embeds `file` in the assembly with the resource name of Security.Evidence.

You cannot use Security.Evidence for regular resources.| |**/fileversion:** `version`|Specifies a string for the **File Version** field in the assembly. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/fileversion** will be used as the Win32 **File Version** resource. If you do not specify **/fileversion**, the Win32 **File Version** resource will be populated by the Win32 **Assembly Version** resource.

If **/win32res** is specified, **/fileversion** does not affect the Win32 resource.

You can also specify this option as a custom attribute (AssemblyFileVersionAttribute) in the source code for any CIL module.| diff --git a/docs/framework/tools/caspol-exe-code-access-security-policy-tool.md b/docs/framework/tools/caspol-exe-code-access-security-policy-tool.md index c754535085c9e..b5c9b0b194d89 100644 --- a/docs/framework/tools/caspol-exe-code-access-security-policy-tool.md +++ b/docs/framework/tools/caspol-exe-code-access-security-policy-tool.md @@ -53,7 +53,7 @@ caspol [options] |**-cu**[**stomuser**] *path*|Allows the administration of a custom user policy that doesn't belong to the user on whose behalf Caspol.exe is currently running. You must specify the location of the custom user's security configuration file with the *path* argument.| |**-enterprise**

or

**-en**|Indicates that all options following this one apply to the enterprise level policy. Users who aren't enterprise administrators don't have sufficient rights to modify the enterprise policy, although they can view it. In non-enterprise scenarios, this policy, by default, doesn't interfere with machine and user policy.| |**-e**[**xecution**] {**on** | **off**}|Turns on or off the mechanism that checks for the permission to run before code starts to execute. **Note:** This switch is removed in .NET Framework 4 and later versions. | -|**-f**[**orce**]|Suppresses the tool's self-destruct test and changes the policy as specified by the user. Normally, Caspol.exe checks whether any policy changes would prevent Caspol.exe itself from running properly; if so, Caspol.exe doesn't save the policy change and prints an error message. To force Caspol.exe to change policy even if this prevents Caspol.exe itself from running, use the **–force** option.| +|**-f**[**orce**]|Suppresses the tool's self-destruct test and changes the policy as specified by the user. Normally, Caspol.exe checks whether any policy changes would prevent Caspol.exe itself from running properly; if so, Caspol.exe doesn't save the policy change and prints an error message. To force Caspol.exe to change policy even if this prevents Caspol.exe itself from running, use the **-force** option.| |**-h**[**elp**]|Displays command syntax and options for Caspol.exe.| |**-l**[**ist**]|Lists the code group hierarchy and the permission sets for the specified machine, user, enterprise, or all policy levels. Caspol.exe displays the code group's label first, followed by the name, if it isn't null.| |**-listdescription**

or

**-ld**|Lists all code group descriptions for the specified policy level.| @@ -80,7 +80,7 @@ caspol [options] |Argument|Description| |--------------|-----------------| |**-allcode**|Specifies all code. For more information about this membership condition, see .| -|**-appdir**|Specifies the application directory. If you specify **–appdir** as the membership condition, the URL evidence of code is compared with the application directory evidence of that code. If both evidence values are the same, this membership condition is satisfied. For more information about this membership condition, see .| +|**-appdir**|Specifies the application directory. If you specify **-appdir** as the membership condition, the URL evidence of code is compared with the application directory evidence of that code. If both evidence values are the same, this membership condition is satisfied. For more information about this membership condition, see .| |**-custom** *xmlfile*|Adds a custom membership condition. The mandatory *xmlfile* argument specifies the .xml file that contains XML serialization of the custom membership condition.| |**-hash** *hashAlg* {**-hex** *hashValue* | **-file** *assembly_file* }|Specifies code that has the given assembly hash. To use a hash as a code group membership condition, you must specify either the hash value or the assembly file. For more information about this membership condition, see .| |**-pub** { **-cert** *cert_file_name* |

**-file** *signed_file_name* | **-hex** *hex_string* }|Specifies code that has the given software publisher, as denoted by a certificate file, a signature on a file, or the hexadecimal representation of an X509 certificate. For more information about this membership condition, see .| @@ -89,18 +89,18 @@ caspol [options] |**-url** *URL*|Specifies code that originates from the given URL. The URL must include a protocol, such as `http://` or `ftp://`. Additionally, a wildcard character (\*) can be used to specify multiple assemblies from a particular URL. **Note:** Because a URL can be identified using multiple names, using a URL as a membership condition isn't a safe way to ascertain the identity of code. Where possible, use a strong name membership condition, a publisher membership condition, or the hash membership condition.

For more information about this membership condition, see .| |**-zone** *zonename*|Specifies code with the given zone of origin. The *zonename* argument can be one of the following values: **MyComputer**, **Intranet**, **Trusted**, **Internet**, or **Untrusted**. For more information about this membership condition, see the Class.| - The *flags* argument, which can be used with the **–addgroup** and **–chggroup** options, is specified using one of the following. + The *flags* argument, which can be used with the **-addgroup** and **-chggroup** options, is specified using one of the following. |Argument|Description| |--------------|-----------------| -|**-description** "*description*"|If used with the **–addgroup** option, specifies the description for a code group to add. If used with the **–chggroup** option, specifies the description for a code group to edit. The *description* argument must be enclosed in double quotes.| +|**-description** "*description*"|If used with the **-addgroup** option, specifies the description for a code group to add. If used with the **-chggroup** option, specifies the description for a code group to edit. The *description* argument must be enclosed in double quotes.| |**-exclusive** {**on**|**off**}|When set to **on**, indicates that only the permission set associated with the code group you're adding or modifying is considered when some code fits the membership condition of the code group. When this option is set to **off**, Caspol.exe considers the permission sets of all matching code groups in the policy level.| |**-levelfinal** {**on**|**off**}|When set to **on**, indicates that no policy level below the level in which the added or modified code group occurs is considered. This option is typically used at the machine policy level. For example, if you set this flag for a code group at the machine level and some code matches this code group's membership condition, Caspol.exe does not calculate or apply the user level policy for this code.| -|**-name** "*name*"|If used with the **–addgroup** option, specifies the scripting name for a code group to add. If used with the **-chggroup** option, specifies the scripting name for a code group to edit. The *name* argument must be enclosed in double quotes. The *name* argument cannot begin with a number, and can only contain A-Z, 0-9, and the underscore character. Code groups can be referred to by this *name* instead of by their numeric label. The *name* is also highly useful for scripting purposes.| +|**-name** "*name*"|If used with the **-addgroup** option, specifies the scripting name for a code group to add. If used with the **-chggroup** option, specifies the scripting name for a code group to edit. The *name* argument must be enclosed in double quotes. The *name* argument cannot begin with a number, and can only contain A-Z, 0-9, and the underscore character. Code groups can be referred to by this *name* instead of by their numeric label. The *name* is also highly useful for scripting purposes.| ## Remarks - Security policy is expressed using three policy levels: machine policy, user policy, and enterprise policy. The set of permissions that an assembly receives is determined by the intersection of the permission sets allowed by these three policy levels. Each policy level is represented by a hierarchical structure of code groups. Every code group has a membership condition that determines which code is a member of that group. A named permission set is also associated with each code group. This permission set specifies the permissions the runtime allows code that satisfies the membership condition to have. A code group hierarchy, along with its associated named permission sets, defines and maintains each level of security policy. You can use the **–user**, **-customuser**, **–machine** and **-enterprise** options to set the level of security policy. + Security policy is expressed using three policy levels: machine policy, user policy, and enterprise policy. The set of permissions that an assembly receives is determined by the intersection of the permission sets allowed by these three policy levels. Each policy level is represented by a hierarchical structure of code groups. Every code group has a membership condition that determines which code is a member of that group. A named permission set is also associated with each code group. This permission set specifies the permissions the runtime allows code that satisfies the membership condition to have. A code group hierarchy, along with its associated named permission sets, defines and maintains each level of security policy. You can use the **-user**, **-customuser**, **-machine** and **-enterprise** options to set the level of security policy. For more information about security policy and how the runtime determines which permissions to grant to code, see [Security Policy Management](/previous-versions/dotnet/netframework-4.0/c1k0eed6(v=vs.100)). @@ -108,7 +108,7 @@ caspol [options] To facilitate references to code groups in a hierarchy, the **-list** option displays an indented list of code groups along with their numerical labels (1, 1.1, 1.1.1, and so on). The other command-line operations that target code groups also use the numerical labels to refer to specific code groups. - Named permission sets are referenced by their names. The **–list** option displays the list of code groups followed by a list of named permission sets available in that policy. + Named permission sets are referenced by their names. The **-list** option displays the list of code groups followed by a list of named permission sets available in that policy. ## Caspol.exe Behavior @@ -116,15 +116,15 @@ caspol [options] The **-s**[**ecurity**] {**on** | **off**} option is a computer-wide operation. Turning off code access security terminates security checks for all managed code and for all users on the computer. If side-by-side versions of the .NET Framework are installed, this command turns off security for every version installed on the computer. Although the **-list** option shows that security is turned off, nothing else clearly indicates for other users that security has been turned off. - When a user without administrative rights runs Caspol.exe, all options refer to the user level policy unless the **–machine** option is specified. When an administrator runs Caspol.exe, all options refer to the machine policy unless the **–user** option is specified. + When a user without administrative rights runs Caspol.exe, all options refer to the user level policy unless the **-machine** option is specified. When an administrator runs Caspol.exe, all options refer to the machine policy unless the **-user** option is specified. - Caspol.exe must be granted the equivalent of the **Everything** permission set to function. The tool has a protective mechanism that prevents policy from being modified in ways that would prevent Caspol.exe from being granted the permissions it needs to run. If you try to make such changes, Caspol.exe notifies you that the requested policy change will break the tool, and the policy change is rejected. You can turn off this protective mechanism for a given command by using the **–force** option. + Caspol.exe must be granted the equivalent of the **Everything** permission set to function. The tool has a protective mechanism that prevents policy from being modified in ways that would prevent Caspol.exe from being granted the permissions it needs to run. If you try to make such changes, Caspol.exe notifies you that the requested policy change will break the tool, and the policy change is rejected. You can turn off this protective mechanism for a given command by using the **-force** option. ## Manually Editing the Security Configuration Files - Three security configuration files correspond to the three policy levels supported by Caspol.exe: one for the machine policy, one for a given user's policy, and one for the enterprise policy. These files are created on disk only when machine, user, or enterprise policy is changed using Caspol.exe. You can use the **–reset** option in Caspol.exe to save the default security policy to disk, if needed. + Three security configuration files correspond to the three policy levels supported by Caspol.exe: one for the machine policy, one for a given user's policy, and one for the enterprise policy. These files are created on disk only when machine, user, or enterprise policy is changed using Caspol.exe. You can use the **-reset** option in Caspol.exe to save the default security policy to disk, if needed. In most cases, manually editing the security configuration files isn't recommended. But there might be scenarios in which modifying these files becomes necessary, such as when an administrator wants to edit the security configuration for a particular user. diff --git a/docs/framework/tools/mdbg-exe.md b/docs/framework/tools/mdbg-exe.md index 05bd997528bc5..4f547c574743b 100644 --- a/docs/framework/tools/mdbg-exe.md +++ b/docs/framework/tools/mdbg-exe.md @@ -62,7 +62,7 @@ MDbg [ProgramName[arguments]] [options] |**o**[**ut**]|Moves to the end of the current function.| |**pa**[**th**] [*pathName*]|Searches the specified path for the source files if the location in the binaries is not available.| |**p**[**rint**] [*var*] | [`-d`]|Prints all variables in scope (**print**), prints the specified variable (**print** *var*), or prints the debugger variables (**print**`-d`).| -|**printe**[**xception**] [*-r*]|Prints the last exception on the current thread. Use the `–r` (recursive) option to traverse the `InnerException` property on the exception object to get information about the entire chain of exceptions.| +|**printe**[**xception**] [*-r*]|Prints the last exception on the current thread. Use the `-r` (recursive) option to traverse the `InnerException` property on the exception object to get information about the entire chain of exceptions.| |**pro**[**cessenum**]|Displays the active processes.| |**q**[**uit**] [*exitcode*]|Quits the MDbg.exe shell, optionally specifying the process exit code.| |**re**[**sume**] [`*` | [`~`]*threadNumber*]|Resumes the current thread or the thread specified by the *threadNumber* parameter.

If the *threadNumber* parameter is specified as `*` or if the thread number starts with `~`, the command applies to all threads except the one specified by *threadNumber*.

Resuming a non-suspended thread has no effect.| diff --git a/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md b/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md index 8b483cd29b29b..9e7f2c8e711d8 100644 --- a/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md +++ b/docs/framework/tools/mpgo-exe-managed-profile-guided-optimization-tool.md @@ -1,14 +1,13 @@ --- title: "Mpgo.exe (Managed Profile Guided Optimization Tool)" description: Use Mpgo.exe, the Managed Profile Guided Optimization Tool. With this tool, optimize native image assemblies created by the Native Image Generator (Ngen.exe). -ms.date: "03/30/2017" +ms.date: 11/24/2025 helpviewer_keywords: - "Mpgo.exe" - "training scenarios, generating profiles with" - "Managed Profile Guided Optimization Tool" - "Ngen.exe" - "Ngen.exe, profilers and native images" -ms.assetid: f6976502-a000-4fbe-aaf5-a7aab9ce4ec2 --- # Mpgo.exe (Managed Profile Guided Optimization Tool) @@ -25,13 +24,13 @@ Enter the following command at the command prompt: For desktop apps: ```console -mpgo –Scenario [-Import ] –AssemblyList ... -OutDir [options] +mpgo -Scenario [-Import ] -AssemblyList ... -OutDir [options] ``` For Windows 8.x Store apps: ```console -mpgo –Scenario -AppID -Timeout +mpgo -Scenario -AppID -Timeout ``` ## Parameters @@ -39,11 +38,11 @@ mpgo –Scenario -AppID -Timeout All arguments to Mpgo.exe are case-insensitive. Commands are prefixed with a dash. > [!NOTE] -> You can use either `–Scenario` or `–Import` as a required command, but not both. None of the required parameters are used if you specify the `–Reset` option. +> You can use either `-Scenario` or `-Import` as a required command, but not both. None of the required parameters are used if you specify the `-Reset` option. |Required parameter|Description| |------------------------|-----------------| -|`-Scenario` \<*command*>

—or—

`-Scenario` \<*packageName*>

-or-

`-Import` \<*directory*>|For desktop apps, use `–Scenario` to specify the command to run the application you want to optimize, including any command-line arguments. Use three sets of double quotation marks around *command* if it specifies a path that includes spaces; for example: `mpgo.exe -scenario """C:\My App\myapp.exe""" -assemblylist """C:\My App\myapp.exe""" -outdir "C:\optimized files"`. Do not use double quotation marks; they will not work correctly if *command* includes spaces.

-or-

For Windows 8.x Store apps, use `–Scenario` to specify the package that you want to generate profile information for. If you specify the package display name or the package family name instead of the full package name, Mpgo.exe will select the package that matches the name you provided if there is only one match. If multiple packages match the specified name, Mpgo.exe will prompt you to choose a package.

—or—

Use `-Import` to specify that optimization data from previously optimized assemblies should be used to optimize the assemblies in `-AssemblyList`. *directory* specifies the directory that contains the previously optimized files. The assemblies specified in `–AssemblyList` or `–AssemblyListFile` are the new versions of the assemblies to be optimized using the data from the imported files. Using optimization data from older version of assemblies enables you to optimize newer versions of assemblies without re-running the scenario. However, if the imported and target assemblies include significantly different code, the optimization data will be ineffective. The assembly names specified in `–AssemblyList` or `–AssemblyListFile` must be present in the directory specified by `–Import`*directory*. Use three sets of double quotation marks around *directory* if it specifies a path that includes spaces.

You must specify either `–Scenario` or `–Import`, but not both parameters.| +|`-Scenario` \<*command*>

—or—

`-Scenario` \<*packageName*>

-or-

`-Import` \<*directory*>|For desktop apps, use `-Scenario` to specify the command to run the application you want to optimize, including any command-line arguments. Use three sets of double quotation marks around *command* if it specifies a path that includes spaces; for example: `mpgo.exe -scenario """C:\My App\myapp.exe""" -assemblylist """C:\My App\myapp.exe""" -outdir "C:\optimized files"`. Do not use double quotation marks; they will not work correctly if *command* includes spaces.

-or-

For Windows 8.x Store apps, use `-Scenario` to specify the package that you want to generate profile information for. If you specify the package display name or the package family name instead of the full package name, Mpgo.exe will select the package that matches the name you provided if there is only one match. If multiple packages match the specified name, Mpgo.exe will prompt you to choose a package.

—or—

Use `-Import` to specify that optimization data from previously optimized assemblies should be used to optimize the assemblies in `-AssemblyList`. *directory* specifies the directory that contains the previously optimized files. The assemblies specified in `-AssemblyList` or `-AssemblyListFile` are the new versions of the assemblies to be optimized using the data from the imported files. Using optimization data from older version of assemblies enables you to optimize newer versions of assemblies without re-running the scenario. However, if the imported and target assemblies include significantly different code, the optimization data will be ineffective. The assembly names specified in `-AssemblyList` or `-AssemblyListFile` must be present in the directory specified by `-Import`*directory*. Use three sets of double quotation marks around *directory* if it specifies a path that includes spaces.

You must specify either `-Scenario` or `-Import`, but not both parameters.| |`-OutDir` \<*directory*>|The directory in which to place the optimized assemblies. If an assembly already exists in the output directory folder, a new copy is created and an index number is appended to its name; for example: *assemblyname*-1.exe. Use double quotation marks around *directory* if it specifies a path that contains spaces.| |`-AssemblyList` \<*assembly1 assembly2 ...*>

—or—

`-AssemblyListFile` \<*file*>|A list of assemblies (including .exe and .dll files), separated by spaces, that you want collect profile information about. You can specify `C:\Dir\*.dll` or `*.dll` to select all the assemblies in the designated or current working directory. See the Remarks section for more information.

—or—

A text file that contains the list of assemblies you want to collect profile information about, listed one assembly per line. If an assembly name begins with a hyphen (-), use an assembly file list or rename the assembly.| |`-AppID` \<*appId*>|The ID of the application in the specified package. If you use the wildcard (\*), Mpgo.exe will try to enumerate the AppIDs in the package and will fall back to \<*package_family_name*>!App if it fails. If you specify a string that is prefixed by an exclamation point (!), Mpgo.exe will concatenate the package family name with the argument provided.| @@ -56,12 +55,12 @@ mpgo –Scenario -AppID -Timeout |`-f`|Forces the inclusion of the profile data in a binary assembly, even if it's signed. If the assembly is signed, it must be re-signed; otherwise, the assembly will fail to load and run.| |`-Reset`|Resets the environment to make certain that an aborted profiling session doesn't affect your assemblies, and then quits. The environment is reset by default before and after a profiling session.| |`-Timeout` \<*time in seconds*>|Specifies the profiling duration in seconds. Use a value that is slightly more than your observed startup times for GUI applications. At the end of the time-out period, the profile data is recorded although the application continues to run. If you don't set this option, profiling will continue until application shutdown, at which time the data will be recorded.| -|`-LeaveNativeImages`|Specifies that the instrumented native images shouldn't be removed after running the scenario. This option is primarily used when you're getting the application that you specified for the scenario running. It will prevent the recreation of native images for subsequent runs of Mpgo.exe. When you have finished running your application, there may be orphaned native images in the cache if you specify this option. In this case, run Mpgo.exe with the same scenario and assembly list and use the `–RemoveNativeImages` parameter to remove these native images.| -|`-RemoveNativeImages`|Cleans up from a run where `–LeaveNativeImages` was specified. If you specify `-RemoveNativeImages`, Mpgo.exe ignores any arguments except `-64bit` and `–AssemblyList`, and exits after removing all instrumented native images.| +|`-LeaveNativeImages`|Specifies that the instrumented native images shouldn't be removed after running the scenario. This option is primarily used when you're getting the application that you specified for the scenario running. It will prevent the recreation of native images for subsequent runs of Mpgo.exe. When you have finished running your application, there may be orphaned native images in the cache if you specify this option. In this case, run Mpgo.exe with the same scenario and assembly list and use the `-RemoveNativeImages` parameter to remove these native images.| +|`-RemoveNativeImages`|Cleans up from a run where `-LeaveNativeImages` was specified. If you specify `-RemoveNativeImages`, Mpgo.exe ignores any arguments except `-64bit` and `-AssemblyList`, and exits after removing all instrumented native images.| ## Remarks - You can use both `–AssemblyList` and `- AssemblyListFile` multiple times on the command line. + You can use both `-AssemblyList` and `-AssemblyListFile` multiple times on the command line. If you do not specify full path names when specifying assemblies, Mpgo.exe looks in the current directory. If you specify an incorrect path, Mpgo.exe displays an error message but continues to generate data for other assemblies. If you specify an assembly that is not loaded during the training scenario, no training data is generated for that assembly. @@ -78,19 +77,19 @@ mpgo –Scenario -AppID -Timeout 2. Run Mpgo.exe as an administrator with the necessary parameters. See the next section for sample commands. - The optimized intermediate language (IL) assemblies are created in the folder specified by the `–OutDir` parameter (in the examples, this is the `C:\Optimized` folder). + The optimized intermediate language (IL) assemblies are created in the folder specified by the `-OutDir` parameter (in the examples, this is the `C:\Optimized` folder). -3. Replace the IL assemblies you used for Ngen.exe with the new IL assemblies that contain the profile information from the directory specified by `–OutDir`. +3. Replace the IL assemblies you used for Ngen.exe with the new IL assemblies that contain the profile information from the directory specified by `-OutDir`. 4. The application setup (using the images provided by Mpgo.exe) will install optimized native images. ## Suggested Workflow -1. Create a set of optimized IL assemblies by using Mpgo.exe with the `–Scenario` parameter. +1. Create a set of optimized IL assemblies by using Mpgo.exe with the `-Scenario` parameter. 2. Check the optimized IL assemblies into source control. -3. In the build process, call Mpgo.exe with the `–Import` parameter as a post-build step to generate optimized IL images to pass to Ngen.exe. +3. In the build process, call Mpgo.exe with the `-Import` parameter as a post-build step to generate optimized IL images to pass to Ngen.exe. This process ensures that all assemblies have optimization data. If you check in updated optimized assemblies (steps 1 and 2) more frequently, the performance numbers will be more consistent throughout product development. @@ -98,9 +97,9 @@ mpgo –Scenario -AppID -Timeout You can run Mpgo.exe from Visual Studio (see the article [How to: Specify Build Events (C#)](/visualstudio/ide/how-to-specify-build-events-csharp)) with the following restrictions: -- You cannot use quoted paths with trailing slash marks, because Visual Studio macros also use trailing slash marks by default. (For example, `–OutDir "C:\Output Folder\"` is invalid.) To work around this restriction, you can escape the trailing slash. (For example, use `-OutDir "$(OutDir)\"` instead.) +- You cannot use quoted paths with trailing slash marks, because Visual Studio macros also use trailing slash marks by default. (For example, `-OutDir "C:\Output Folder\"` is invalid.) To work around this restriction, you can escape the trailing slash. (For example, use `-OutDir "$(OutDir)\"` instead.) -- By default, Mpgo.exe is not on the Visual Studio build path. You must either add the path to Visual Studio or specify the full path on the Mpgo command line. You can use either the `–Scenario` or the `–Import` parameter in the post-build event in Visual Studio. However, the typical process is to use `–Scenario` one time from a Developer Command Prompt for Visual Studio, and then use `–Import` to update the optimized assemblies after each build; for example: `"C:\Program Files\Microsoft Visual Studio 11.0\Team Tools\Performance Tools\mpgo.exe" -import "$(OutDir)tmp" -assemblylist "$(TargetPath)" -outdir "$(OutDir)\"`. +- By default, Mpgo.exe is not on the Visual Studio build path. You must either add the path to Visual Studio or specify the full path on the Mpgo command line. You can use either the `-Scenario` or the `-Import` parameter in the post-build event in Visual Studio. However, the typical process is to use `-Scenario` one time from a Developer Command Prompt for Visual Studio, and then use `-Import` to update the optimized assemblies after each build; for example: `"C:\Program Files\Microsoft Visual Studio 11.0\Team Tools\Performance Tools\mpgo.exe" -import "$(OutDir)tmp" -assemblylist "$(TargetPath)" -outdir "$(OutDir)\"`. @@ -109,13 +108,13 @@ mpgo –Scenario -AppID -Timeout The following Mpgo.exe command from a Developer Command Prompt for Visual Studio optimizes a tax application: ```console -mpgo –scenario "C:\MyApp\MyTax.exe /params par" –AssemblyList Mytax.dll MyTaxUtil2011.dll –OutDir C:\Optimized –TimeOut 15 +mpgo -scenario "C:\MyApp\MyTax.exe /params par" -AssemblyList Mytax.dll MyTaxUtil2011.dll -OutDir C:\Optimized -TimeOut 15 ``` The following Mpgo.exe command optimizes a sound application: ```console -mpgo –scenario "C:\MyApp\wav2wma.exe –input song1.wav –output song1.wma" –AssemblyList transcode.dll –OutDir C:\Optimized –TimeOut 15 +mpgo -scenario "C:\MyApp\wav2wma.exe -input song1.wav -output song1.wma" -AssemblyList transcode.dll -OutDir C:\Optimized -TimeOut 15 ``` The following Mpgo.exe command uses data from previously optimized assemblies to optimize newer versions of the assemblies: diff --git a/docs/framework/tools/resgen-exe-resource-file-generator.md b/docs/framework/tools/resgen-exe-resource-file-generator.md index f9b90b2e08682..49d9e8e1e2428 100644 --- a/docs/framework/tools/resgen-exe-resource-file-generator.md +++ b/docs/framework/tools/resgen-exe-resource-file-generator.md @@ -2,7 +2,7 @@ title: "Resgen.exe (Resource File Generator)" description: Use Resgen.exe, the Resource File Generator. Convert text (.txt, .restext) and XML resource format (.resx) files to embeddable CLR runtime binaries (.resources). ms.date: 10/23/2023 -helpviewer_keywords: +helpviewer_keywords: - "resource files, .resources files" - "resource files, .resx files" - "resx files (resource files)" @@ -34,7 +34,7 @@ Resgen.exe is a general-purpose resource conversion utility that performs the fo - Creates a strongly typed class that provides access to individual named resources and to the instance. - If Resgen.exe fails for any reason, the return value is –1. + If Resgen.exe fails for any reason, the return value is -1. To get help with Resgen.exe, you can use the following command, with no options specified, to display the command syntax and options for Resgen.exe: diff --git a/docs/framework/tools/sn-exe-strong-name-tool.md b/docs/framework/tools/sn-exe-strong-name-tool.md index 0c4d56e11dd41..798238317bfe3 100644 --- a/docs/framework/tools/sn-exe-strong-name-tool.md +++ b/docs/framework/tools/sn-exe-strong-name-tool.md @@ -62,7 +62,7 @@ sn [-quiet][option [parameter(s)]] |`-TSc assembly container`|Test-signs the signed or partially signed *assembly* with the key pair in the key container *container*.| |`-v assembly`|Verifies the strong name in *assembly*, where *assembly* is the name of a file that contains an assembly manifest.| |`-vf assembly`|Verifies the strong name in *assembly.* Unlike the **-v** option, **-vf** forces verification even if it is disabled using the **-Vr** option.| -|`-Vk regfile.reg assembly [userlist] [infile]`|Creates a registration entries (.reg) file you can use to register the specified assembly for verification skipping. The rules for assembly naming that apply to the **-Vr** option apply to **–Vk** as well. For information about the *userlist* and *infile* options, see the **–Vr** option.| +|`-Vk regfile.reg assembly [userlist] [infile]`|Creates a registration entries (.reg) file you can use to register the specified assembly for verification skipping. The rules for assembly naming that apply to the **-Vr** option apply to **-Vk** as well. For information about the *userlist* and *infile* options, see the **-Vr** option.| |`-Vl`|Lists current settings for strong-name verification on this computer.| |`-Vr assembly [userlist] [infile]`|Registers *assembly* for verification skipping. Optionally, you can specify a comma-separated list of user names the skip verification should apply to. If you specify *infile*, verification remains enabled, but the public key in *infile* is used in verification operations. You can specify *assembly* in the form *\*, strongname* to register all assemblies with the specified strong name. For *strongname*, specify the string of hexadecimal digits representing the tokenized form of the public key. See the **-t** and **-T** options to display the public key token. **Caution:** Use this option only during development. Adding an assembly to the skip verification list creates a security vulnerability. A malicious assembly could use the fully specified assembly name (assembly name, version, culture, and public key token) of the assembly added to the skip verification list to fake its identity. This would allow the malicious assembly to also skip verification.| |`-Vu assembly`|Unregisters *assembly* for verification skipping. The same rules for assembly naming that apply to **-Vr** apply to **-Vu**.| @@ -74,10 +74,10 @@ sn [-quiet][option [parameter(s)]] ## Remarks - The **-R** and **–Rc** options are useful with assemblies that have been delay-signed. In this scenario, only the public key has been set at compile time and signing is performed later, when the private key is known. + The **-R** and **-Rc** options are useful with assemblies that have been delay-signed. In this scenario, only the public key has been set at compile time and signing is performed later, when the private key is known. > [!NOTE] -> For parameters (for example, –**Vr)** that write to protected resources such as the registry, run SN.exe as an administrator. +> For parameters (for example, -**Vr)** that write to protected resources such as the registry, run SN.exe as an administrator. The Strong Name tool assumes that public/private key pairs are generated with the `AT_SIGNATURE` algorithm identifier. Public/private key pairs generated with the `AT_KEYEXCHANGE` algorithm generate an error. diff --git a/docs/framework/unmanaged-api/profiling/icorprofilercallback-movedreferences-method.md b/docs/framework/unmanaged-api/profiling/icorprofilercallback-movedreferences-method.md index 6a404fd9b7e20..3432d242eef18 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilercallback-movedreferences-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilercallback-movedreferences-method.md @@ -2,88 +2,88 @@ description: "Learn more about: ICorProfilerCallback::MovedReferences Method" title: "ICorProfilerCallback::MovedReferences Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerCallback.MovedReferences" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerCallback::MovedReferences" -helpviewer_keywords: +helpviewer_keywords: - "MovedReferences method [.NET Framework profiling]" - "ICorProfilerCallback::MovedReferences method [.NET Framework profiling]" ms.assetid: 996c71ae-0676-4616-a085-84ebf507649d -topic_type: +topic_type: - "apiref" --- # ICorProfilerCallback::MovedReferences Method -Called to report the new layout of objects in the heap as a result of a compacting garbage collection. - -## Syntax - -```cpp -HRESULT MovedReferences( - [in] ULONG cMovedObjectIDRanges, - [in, size_is(cMovedObjectIDRanges)] ObjectID oldObjectIDRangeStart[] , - [in, size_is(cMovedObjectIDRanges)] ObjectID newObjectIDRangeStart[] , - [in, size_is(cMovedObjectIDRanges)] ULONG cObjectIDRangeLength[] ); -``` - -## Parameters - - `cMovedObjectIDRanges` - [in] The number of blocks of contiguous objects that moved as the result of the compacting garbage collection. That is, the value of `cMovedObjectIDRanges` is the total size of the `oldObjectIDRangeStart`, `newObjectIDRangeStart`, and `cObjectIDRangeLength` arrays. - - The next three arguments of `MovedReferences` are parallel arrays. In other words, `oldObjectIDRangeStart[i]`, `newObjectIDRangeStart[i]`, and `cObjectIDRangeLength[i]` all concern a single block of contiguous objects. - - `oldObjectIDRangeStart` - [in] An array of `ObjectID` values, each of which is the old (pre-garbage collection) starting address of a block of contiguous, live objects in memory. - - `newObjectIDRangeStart` - [in] An array of `ObjectID` values, each of which is the new (post-garbage collection) starting address of a block of contiguous, live objects in memory. - - `cObjectIDRangeLength` - [in] An array of integers, each of which is the size of a block of contiguous objects in memory. - - A size is specified for each block that is referenced in the `oldObjectIDRangeStart` and `newObjectIDRangeStart` arrays. - -## Remarks - +Called to report the new layout of objects in the heap as a result of a compacting garbage collection. + +## Syntax + +```cpp +HRESULT MovedReferences( + [in] ULONG cMovedObjectIDRanges, + [in, size_is(cMovedObjectIDRanges)] ObjectID oldObjectIDRangeStart[] , + [in, size_is(cMovedObjectIDRanges)] ObjectID newObjectIDRangeStart[] , + [in, size_is(cMovedObjectIDRanges)] ULONG cObjectIDRangeLength[] ); +``` + +## Parameters + + `cMovedObjectIDRanges` + [in] The number of blocks of contiguous objects that moved as the result of the compacting garbage collection. That is, the value of `cMovedObjectIDRanges` is the total size of the `oldObjectIDRangeStart`, `newObjectIDRangeStart`, and `cObjectIDRangeLength` arrays. + + The next three arguments of `MovedReferences` are parallel arrays. In other words, `oldObjectIDRangeStart[i]`, `newObjectIDRangeStart[i]`, and `cObjectIDRangeLength[i]` all concern a single block of contiguous objects. + + `oldObjectIDRangeStart` + [in] An array of `ObjectID` values, each of which is the old (pre-garbage collection) starting address of a block of contiguous, live objects in memory. + + `newObjectIDRangeStart` + [in] An array of `ObjectID` values, each of which is the new (post-garbage collection) starting address of a block of contiguous, live objects in memory. + + `cObjectIDRangeLength` + [in] An array of integers, each of which is the size of a block of contiguous objects in memory. + + A size is specified for each block that is referenced in the `oldObjectIDRangeStart` and `newObjectIDRangeStart` arrays. + +## Remarks + > [!IMPORTANT] -> This method reports sizes as `MAX_ULONG` for objects that are greater than 4 GB on 64-bit platforms. To get the size of objects that are larger than 4 GB, use the [ICorProfilerCallback4::MovedReferences2](icorprofilercallback4-movedreferences2-method.md) method instead. - - A compacting garbage collector reclaims the memory occupied by dead objects and compacts that freed space. As a result, live objects might be moved within the heap, and `ObjectID` values distributed by previous notifications might change. - - Assume that an existing `ObjectID` value (`oldObjectID`) lies within the following range: - - `oldObjectIDRangeStart[i]` <= `oldObjectID` < `oldObjectIDRangeStart[i]` + `cObjectIDRangeLength[i]` - - In this case, the offset from the start of the range to the start of the object is as follows: - - `oldObjectID` - `oldObjectRangeStart[i]` - - For any value of `i` that is in the following range: - - 0 <= `i` < `cMovedObjectIDRanges` - - you can calculate the new `ObjectID` as follows: - - `newObjectID` = `newObjectIDRangeStart[i]` + (`oldObjectID` – `oldObjectIDRangeStart[i]`) - - None of the `ObjectID` values passed by `MovedReferences` are valid during the callback itself, because the garbage collection might be in the middle of moving objects from old locations to new locations. Therefore, profilers should not attempt to inspect objects during a `MovedReferences` call. A [ICorProfilerCallback2::GarbageCollectionFinished](icorprofilercallback2-garbagecollectionfinished-method.md) callback indicates that all objects have been moved to their new locations and inspection can be performed. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +> This method reports sizes as `MAX_ULONG` for objects that are greater than 4 GB on 64-bit platforms. To get the size of objects that are larger than 4 GB, use the [ICorProfilerCallback4::MovedReferences2](icorprofilercallback4-movedreferences2-method.md) method instead. + + A compacting garbage collector reclaims the memory occupied by dead objects and compacts that freed space. As a result, live objects might be moved within the heap, and `ObjectID` values distributed by previous notifications might change. + + Assume that an existing `ObjectID` value (`oldObjectID`) lies within the following range: + + `oldObjectIDRangeStart[i]` <= `oldObjectID` < `oldObjectIDRangeStart[i]` + `cObjectIDRangeLength[i]` + + In this case, the offset from the start of the range to the start of the object is as follows: + + `oldObjectID` - `oldObjectRangeStart[i]` + + For any value of `i` that is in the following range: + + 0 <= `i` < `cMovedObjectIDRanges` + + you can calculate the new `ObjectID` as follows: + + `newObjectID` = `newObjectIDRangeStart[i]` + (`oldObjectID` - `oldObjectIDRangeStart[i]`) + + None of the `ObjectID` values passed by `MovedReferences` are valid during the callback itself, because the garbage collection might be in the middle of moving objects from old locations to new locations. Therefore, profilers should not attempt to inspect objects during a `MovedReferences` call. A [ICorProfilerCallback2::GarbageCollectionFinished](icorprofilercallback2-garbagecollectionfinished-method.md) callback indicates that all objects have been moved to their new locations and inspection can be performed. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorProfilerCallback Interface](icorprofilercallback-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilercallback4-movedreferences2-method.md b/docs/framework/unmanaged-api/profiling/icorprofilercallback4-movedreferences2-method.md index 21a30b24c4703..3faee9c86cf6c 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilercallback4-movedreferences2-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilercallback4-movedreferences2-method.md @@ -2,87 +2,87 @@ description: "Learn more about: ICorProfilerCallback4::MovedReferences2 Method" title: "ICorProfilerCallback4::MovedReferences2 Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerCallback4.MovedReferences2" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerCallback4::MovedReferences2" -helpviewer_keywords: +helpviewer_keywords: - "MovedReferences2 method, ICorProfilerCallback4 interface [.NET Framework profiling]" - "ICorProfilerCallback4::MovedReferences2 method [.NET Framework profiling]" ms.assetid: d17a065b-5bc6-4817-b3e1-1e413fcb33a8 -topic_type: +topic_type: - "apiref" --- # ICorProfilerCallback4::MovedReferences2 Method -Called to report the new layout of objects in the heap as a result of a compacting garbage collection. This method is called if the profiler has implemented the [ICorProfilerCallback4](icorprofilercallback4-interface.md) interface. This callback replaces the [ICorProfilerCallback::MovedReferences](icorprofilercallback-movedreferences-method.md) method, because it can report larger ranges of objects whose lengths exceed what can be expressed in a ULONG. - -## Syntax - -```cpp -HRESULT MovedReferences2( - [in] ULONG cMovedObjectIDRanges, - [in, size_is(cMovedObjectIDRanges)] ObjectID oldObjectIDRangeStart[] , - [in, size_is(cMovedObjectIDRanges)] ObjectID newObjectIDRangeStart[] , - [in, size_is(cMovedObjectIDRanges)] SIZE_T cObjectIDRangeLength[] ); -``` - -## Parameters - - `cMovedObjectIDRanges` - [in] The number of blocks of contiguous objects that moved as the result of the compacting garbage collection. That is, the value of `cMovedObjectIDRanges` is the total size of the `oldObjectIDRangeStart`, `newObjectIDRangeStart`, and `cObjectIDRangeLength` arrays. - - The next three arguments of `MovedReferences2` are parallel arrays. In other words, `oldObjectIDRangeStart[i]`, `newObjectIDRangeStart[i]`, and `cObjectIDRangeLength[i]` all concern a single block of contiguous objects. - - `oldObjectIDRangeStart` - [in] An array of `ObjectID` values, each of which is the old (pre-garbage collection) starting address of a block of contiguous, live objects in memory. - - `newObjectIDRangeStart` - [in] An array of `ObjectID` values, each of which is the new (post-garbage collection) starting address of a block of contiguous, live objects in memory. - - `cObjectIDRangeLength` - [in] An array of integers, each of which is the size of a block of contiguous objects in memory. - - A size is specified for each block that is referenced in the `oldObjectIDRangeStart` and `newObjectIDRangeStart` arrays. - -## Remarks - - A compacting garbage collector reclaims the memory occupied by dead objects and compacts that freed space. As a result, live objects might be moved within the heap, and `ObjectID` values distributed by previous notifications might change. - - Assume that an existing `ObjectID` value (`oldObjectID`) lies within the following range: - - `oldObjectIDRangeStart[i]` <= `oldObjectID` < `oldObjectIDRangeStart[i]` + `cObjectIDRangeLength[i]` - - In this case, the offset from the start of the range to the start of the object is as follows: - - `oldObjectID` - `oldObjectRangeStart[i]` - - For any value of `i` that is in the following range: - - 0 <= `i` < `cMovedObjectIDRanges` - - you can calculate the new `ObjectID` as follows: - - `newObjectID` = `newObjectIDRangeStart[i]` + (`oldObjectID` – `oldObjectIDRangeStart[i]`) - - None of the `ObjectID` values passed by `MovedReferences2` are valid during the callback itself, because the garbage collector might be in the middle of moving objects from old locations to new locations. Therefore, profilers should not attempt to inspect objects during a `MovedReferences2` call. A [ICorProfilerCallback2::GarbageCollectionFinished](icorprofilercallback2-garbagecollectionfinished-method.md) callback indicates that all objects have been moved to their new locations and inspection can be performed. - - If the profiler implements both the [ICorProfilerCallback](icorprofilercallback-interface.md) and the [ICorProfilerCallback4](icorprofilercallback4-interface.md) interfaces, the `MovedReferences2` method is called before the [ICorProfilerCallback::MovedReferences](icorprofilercallback-movedreferences-method.md) method, but only if the `MovedReferences2` method returns successfully. Profilers can return an HRESULT that indicates failure from the `MovedReferences2` method, to avoid calling the second method. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v45plus](../../../../includes/net-current-v45plus-md.md)] - +Called to report the new layout of objects in the heap as a result of a compacting garbage collection. This method is called if the profiler has implemented the [ICorProfilerCallback4](icorprofilercallback4-interface.md) interface. This callback replaces the [ICorProfilerCallback::MovedReferences](icorprofilercallback-movedreferences-method.md) method, because it can report larger ranges of objects whose lengths exceed what can be expressed in a ULONG. + +## Syntax + +```cpp +HRESULT MovedReferences2( + [in] ULONG cMovedObjectIDRanges, + [in, size_is(cMovedObjectIDRanges)] ObjectID oldObjectIDRangeStart[] , + [in, size_is(cMovedObjectIDRanges)] ObjectID newObjectIDRangeStart[] , + [in, size_is(cMovedObjectIDRanges)] SIZE_T cObjectIDRangeLength[] ); +``` + +## Parameters + + `cMovedObjectIDRanges` + [in] The number of blocks of contiguous objects that moved as the result of the compacting garbage collection. That is, the value of `cMovedObjectIDRanges` is the total size of the `oldObjectIDRangeStart`, `newObjectIDRangeStart`, and `cObjectIDRangeLength` arrays. + + The next three arguments of `MovedReferences2` are parallel arrays. In other words, `oldObjectIDRangeStart[i]`, `newObjectIDRangeStart[i]`, and `cObjectIDRangeLength[i]` all concern a single block of contiguous objects. + + `oldObjectIDRangeStart` + [in] An array of `ObjectID` values, each of which is the old (pre-garbage collection) starting address of a block of contiguous, live objects in memory. + + `newObjectIDRangeStart` + [in] An array of `ObjectID` values, each of which is the new (post-garbage collection) starting address of a block of contiguous, live objects in memory. + + `cObjectIDRangeLength` + [in] An array of integers, each of which is the size of a block of contiguous objects in memory. + + A size is specified for each block that is referenced in the `oldObjectIDRangeStart` and `newObjectIDRangeStart` arrays. + +## Remarks + + A compacting garbage collector reclaims the memory occupied by dead objects and compacts that freed space. As a result, live objects might be moved within the heap, and `ObjectID` values distributed by previous notifications might change. + + Assume that an existing `ObjectID` value (`oldObjectID`) lies within the following range: + + `oldObjectIDRangeStart[i]` <= `oldObjectID` < `oldObjectIDRangeStart[i]` + `cObjectIDRangeLength[i]` + + In this case, the offset from the start of the range to the start of the object is as follows: + + `oldObjectID` - `oldObjectRangeStart[i]` + + For any value of `i` that is in the following range: + + 0 <= `i` < `cMovedObjectIDRanges` + + you can calculate the new `ObjectID` as follows: + + `newObjectID` = `newObjectIDRangeStart[i]` + (`oldObjectID` - `oldObjectIDRangeStart[i]`) + + None of the `ObjectID` values passed by `MovedReferences2` are valid during the callback itself, because the garbage collector might be in the middle of moving objects from old locations to new locations. Therefore, profilers should not attempt to inspect objects during a `MovedReferences2` call. A [ICorProfilerCallback2::GarbageCollectionFinished](icorprofilercallback2-garbagecollectionfinished-method.md) callback indicates that all objects have been moved to their new locations and inspection can be performed. + + If the profiler implements both the [ICorProfilerCallback](icorprofilercallback-interface.md) and the [ICorProfilerCallback4](icorprofilercallback4-interface.md) interfaces, the `MovedReferences2` method is called before the [ICorProfilerCallback::MovedReferences](icorprofilercallback-movedreferences-method.md) method, but only if the `MovedReferences2` method returns successfully. Profilers can return an HRESULT that indicates failure from the `MovedReferences2` method, to avoid calling the second method. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v45plus](../../../../includes/net-current-v45plus-md.md)] + ## See also - [ICorProfilerCallback Interface](icorprofilercallback-interface.md) diff --git a/docs/framework/wcf/diagnostics/tracing/recommended-settings-for-tracing-and-message-logging.md b/docs/framework/wcf/diagnostics/tracing/recommended-settings-for-tracing-and-message-logging.md index 7f16b26277d79..47c1073425847 100644 --- a/docs/framework/wcf/diagnostics/tracing/recommended-settings-for-tracing-and-message-logging.md +++ b/docs/framework/wcf/diagnostics/tracing/recommended-settings-for-tracing-and-message-logging.md @@ -6,112 +6,112 @@ ms.assetid: c6aca6e8-704e-4779-a9ef-50c46850249e --- # Recommended Settings for Tracing and Message Logging -This topic describes recommended tracing and message logging settings for different operating environments. - -## Recommended Settings for a Production Environment - - For a production environment, if you are using WCF trace sources, set the `switchValue` to Warning. If you are using the WCF `System.ServiceModel` trace source, set the `switchValue` attribute to `Warning` and the `propagateActivity` attribute to `true`. If you are using a user-defined trace source, set the `switchValue` attribute to `Warning, ActivityTracing`. This can be done manually using the [Configuration Editor Tool (SvcConfigEditor.exe)](../../configuration-editor-tool-svcconfigeditor-exe.md). If you do not anticipate a hit in performance, you can set the `switchValue` attribute to `Information` in all the previously mentioned cases, which generates a fairly large amount of trace data. The following example demonstrates these recommended settings. - -```xml - - - - - - - - - - - - - - - - - - - - - - - - -``` - -## Recommended Settings for Deployment or Debugging - - For deployment or debugging environment, choose `Information` or `Verbose`, along with `ActivityTracing` for either a user-defined or `System.ServiceModel` trace source. To enhance debugging, you should also add an additional trace source (`System.ServiceModel.MessageLogging`) to the configuration to enable message logging. Notice that the `switchValue` attribute has no impact on this trace source. - - The following example demonstrates the recommended settings, using a shared listener that utilizes the `XmlWriterTraceListener`. - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - +This topic describes recommended tracing and message logging settings for different operating environments. + +## Recommended Settings for a Production Environment + + For a production environment, if you are using WCF trace sources, set the `switchValue` to Warning. If you are using the WCF `System.ServiceModel` trace source, set the `switchValue` attribute to `Warning` and the `propagateActivity` attribute to `true`. If you are using a user-defined trace source, set the `switchValue` attribute to `Warning, ActivityTracing`. This can be done manually using the [Configuration Editor Tool (SvcConfigEditor.exe)](../../configuration-editor-tool-svcconfigeditor-exe.md). If you do not anticipate a hit in performance, you can set the `switchValue` attribute to `Information` in all the previously mentioned cases, which generates a fairly large amount of trace data. The following example demonstrates these recommended settings. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + +``` + +## Recommended Settings for Deployment or Debugging + + For deployment or debugging environment, choose `Information` or `Verbose`, along with `ActivityTracing` for either a user-defined or `System.ServiceModel` trace source. To enhance debugging, you should also add an additional trace source (`System.ServiceModel.MessageLogging`) to the configuration to enable message logging. Notice that the `switchValue` attribute has no impact on this trace source. + + The following example demonstrates the recommended settings, using a shared listener that utilizes the `XmlWriterTraceListener`. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + - - - -``` - -## Using WMI to Modify Settings - - You can use WMI to change configuration settings at run time (by enabling the `wmiProviderEnabled` attribute in the configuration, as demonstrated in the previously configuration example). For example, you can use WMI within the CIM Studio to change the trace source levels from Warning to Information at run time. You should be aware that the performance cost of live debugging in this way can be very high. For more information about using WMI, see the [Using Windows Management Instrumentation for Diagnostics](../wmi/index.md) topic. - -## Enable Correlated Events in ASP.NET Tracing - - ASP.NET events do not set the correlation ID (ActivityID) unless ASP.NET event tracing is turned on. To see correlated events properly, you have to turn on ASP.NET events tracing using the following command in the command console, which can be invoked by going to **Start**, **Run** and type **cmd**, - -```console -logman start mytrace -pf logman.providers -o test.etl –ets -``` - - To turn off tracing of ASP.NET events, use the following command, - + /> + + + +``` + +## Using WMI to Modify Settings + + You can use WMI to change configuration settings at run time (by enabling the `wmiProviderEnabled` attribute in the configuration, as demonstrated in the previously configuration example). For example, you can use WMI within the CIM Studio to change the trace source levels from Warning to Information at run time. You should be aware that the performance cost of live debugging in this way can be very high. For more information about using WMI, see the [Using Windows Management Instrumentation for Diagnostics](../wmi/index.md) topic. + +## Enable Correlated Events in ASP.NET Tracing + + ASP.NET events do not set the correlation ID (ActivityID) unless ASP.NET event tracing is turned on. To see correlated events properly, you have to turn on ASP.NET events tracing using the following command in the command console, which can be invoked by going to **Start**, **Run** and type **cmd**, + ```console -logman stop mytrace -ets -``` - +logman start mytrace -pf logman.providers -o test.etl -ets +``` + + To turn off tracing of ASP.NET events, use the following command, + +```console +logman stop mytrace -ets +``` + ## See also - [Using Windows Management Instrumentation for Diagnostics](../wmi/index.md) diff --git a/docs/framework/wcf/feature-details/configuring-ws-atomic-transaction-support.md b/docs/framework/wcf/feature-details/configuring-ws-atomic-transaction-support.md index d4ad997b97110..3e1f66ba31a28 100644 --- a/docs/framework/wcf/feature-details/configuring-ws-atomic-transaction-support.md +++ b/docs/framework/wcf/feature-details/configuring-ws-atomic-transaction-support.md @@ -36,13 +36,13 @@ To register the product, execute the following command from a Command Prompt win To enable the WS-AT protocol service inside MSDTC using port 443 and an X.509 certificate with a private key that has been installed in the local machine store, use the wsatConfig.exe tool with the following command. -`WsatConfig.exe –network:enable –port:8443 –endpointCert: -accountsCerts: -restart` +`WsatConfig.exe -network:enable -port:8443 -endpointCert: -accountsCerts: -restart` Substitute the respective parameters with values relevant to your environment. To disable the WS-AT protocol service inside MSDTC, use the wsatConfig.exe tool with the following command. -`WsatConfig.exe –network:disable -restart` +`WsatConfig.exe -network:disable -restart` ## Configure trust between two machines diff --git a/docs/framework/wcf/feature-details/deploying-an-internet-information-services-hosted-wcf-service.md b/docs/framework/wcf/feature-details/deploying-an-internet-information-services-hosted-wcf-service.md index 6e07ae7365e01..55235ede477fe 100644 --- a/docs/framework/wcf/feature-details/deploying-an-internet-information-services-hosted-wcf-service.md +++ b/docs/framework/wcf/feature-details/deploying-an-internet-information-services-hosted-wcf-service.md @@ -32,7 +32,7 @@ The installation process for .NET Framework automatically registers WCF with IIS - Windows 7 and Windows Server 2003: Use the [ServiceModel Registration Tool (ServiceModelReg.exe)](../servicemodelreg-exe.md) tool to register WCF with IIS. To use this tool, enter `ServiceModelReg.exe /i /x` in [Visual Studio Developer Command Prompt or Visual Studio Developer PowerShell](/visualstudio/ide/reference/command-prompt-powershell). -- Windows 7: Finally, you must verify that ASP.NET is configured to use .NET Framework version 4 or later. You do this by running the ASPNET_Regiis tool with the `–i` option. For more information, see [ASP.NET IIS Registration Tool](/previous-versions/dotnet/netframework-3.5/k6h9cz8h(v=vs.90)). +- Windows 7: Finally, you must verify that ASP.NET is configured to use .NET Framework version 4 or later. You do this by running the ASPNET_Regiis tool with the `-i` option. For more information, see [ASP.NET IIS Registration Tool](/previous-versions/dotnet/netframework-3.5/k6h9cz8h(v=vs.90)). ## Create a New IIS Application or Reuse an Existing ASP.NET Application diff --git a/docs/framework/wcf/find-private-key-tool-findprivatekey-exe.md b/docs/framework/wcf/find-private-key-tool-findprivatekey-exe.md index 942496bb0167e..3cf3b8e7865fc 100644 --- a/docs/framework/wcf/find-private-key-tool-findprivatekey-exe.md +++ b/docs/framework/wcf/find-private-key-tool-findprivatekey-exe.md @@ -45,5 +45,5 @@ FindPrivateKey My CurrentUser -n "CN=John Doe" The following command retrieves the private key for the local machine: ```console -FindPrivateKey My LocalMachine -t "03 33 98 63 d0 47 e7 48 71 33 62 64 76 5c 4c 9d 42 1d 6b 52" –a +FindPrivateKey My LocalMachine -t "03 33 98 63 d0 47 e7 48 71 33 62 64 76 5c 4c 9d 42 1d 6b 52" -a ``` diff --git a/docs/framework/wcf/samples/internet-information-service-hosting-instructions.md b/docs/framework/wcf/samples/internet-information-service-hosting-instructions.md index 08bf9ef6aae46..eaa00a8847e18 100644 --- a/docs/framework/wcf/samples/internet-information-service-hosting-instructions.md +++ b/docs/framework/wcf/samples/internet-information-service-hosting-instructions.md @@ -6,170 +6,170 @@ ms.assetid: 959a21c8-9d9d-4757-b255-4e57793ae9d6 --- # Internet Information Service Hosting Instructions -To run the samples that are hosted by Internet Information Services (IIS), you must make sure that IIS is properly installed and is running. - -### To install IIS version 7.5 on Windows Server 2008 R2 - -1. From **Server Manager**, select **Roles.** Under **Roles Summary**, click **Add Roles**. - -2. Click **Next** to display the **Select Server Roles** dialog. - -3. Select **Application Server** from the **Roles** list, and then click **Next** twice to display the **Select Role Services** dialog for the Application Server role. - -4. Select the **Web Server (IIS)** check box. If you are prompted to install additional role services and features, click **Add Required Features**. Click **Next** twice to display the **Select Role Services** dialog for the Web Server (IIS) role. - -5. Expand **Management Tools**, and then expand **IIS 6 Management Compatibility**. Select **IIS 6 Scripting Tools**. If you are prompted to install additional role services and features, click **Add Required Role Services**. Click **Next**. - -6. If the summary of selections is correct, click **Install**. - -7. When installation completes, click **Close**. - -### To install IIS version 7.5 on Windows 7 - -1. Click **Start**, and then click **Control Panel**. - -2. Open the **Programs** group. - -3. Under **Programs and Features**, click **Turn Windows Features on or off**. - -4. The **User Account Control** dialog is displayed. Click **Continue**. - -5. The **Windows Features** dialog is displayed. Expand the item labeled **Internet Information Services**. - -6. Expand the item labeled **World Wide Web Services**. - -7. Expand the item labeled **Application Development Features**. - -8. Make sure the following items are selected: - - 1. **.NET Extensibility** - - 2. **ASP.NET** - - 3. **ISAPI Extensions** - - 4. **ISAPI Filters** - -9. Under the item labeled **World Wide Web Services**, expand **Common Http Features**. - -10. Make sure **Static Content** is selected. - -11. Under the item labeled **World Wide Web Services**, expand **Security**. - -12. Make sure that **Windows Authentication** is selected. - -13. Under the **Internet Information Services** directory, expand the item labeled **Web Management Tools**, and then select **IIS Management Console**. - -14. Expand the item labeled **IIS 6 Management Compatibility**, and then select **IIS 6 Scripting Tools**. - -15. Under the **Internet Information Services** directory, expand the item labeled **Microsoft .NET Framework 3.5.1**, and then select **Windows Communication Foundation Http Activation**. - -16. Click **OK**. - -### To install IIS version 7.0 on Windows Server 2008 - -1. From **Server Manager**, select **Roles**. Under **Roles Summary**, click **Add Roles**. - -2. Click **Next** to display the **Select Server Roles** dialog. - -3. Select **Application Server** from the **Roles** list, and then click **Next** twice to display the **Select Role Services** dialog for the Application Server role. - -4. Select **Web Server (IIS)** check box. If you are prompted to install additional role services and features, click **Add Required Features**. Click **Next** twice to display the **Select Role Services** dialog for the Web Server (IIS) role. - -5. Expand **Management Tools**, and then expand **IIS 6 Management Compatibility**. Select **IIS 6 Scripting Tools**. If you are prompted to install additional role services and features, click **Add Required Role Services**. Click **Next**. - -6. If the summary of selections is correct, click **Install**. - -7. When installation completes, click **Close**. - -### To install IIS version 7.0 on Windows Vista - -1. Click Start, and then click Control Panel. - -2. Select the **Programs** group. - -3. Under **Programs and Features**, click **Turn Windows Features on or off**. - -4. The **User Account Control** dialog is displayed. Click **Continue**. - -5. The **Windows Features** dialog is displayed. Expand the item labeled **Internet Information Services**. - -6. Expand the item labeled **World Wide Web Services**. - -7. Expand the item labeled **Application Development Features**. - -8. Make sure the following items are selected: - - 1. **.NET Extensibility** - - 2. **ASP.NET** - - 3. **ISAPI Extensions** - - 4. **ISAPI Filters** - -9. Expand the item labeled **Web Management Tools**, and then select **IIS Management Console**. - -10. Under the item labeled **World Wide Web Services**, expand **Common Http Features**. - -11. Make sure **Static Content** is selected. - -12. Under the item labeled **World Wide Web Services**, expand **Security**. - -13. Make sure **Windows Authentication** is selected. - -14. Expand the item labeled **IIS 6 Management Compatibility**, and then select **IIS 6 Scripting Tools**. - -15. Expand the item labeled **Microsoft .NET Framework 3.0**, and then select **Windows Communication Foundation Http Activation**. - -16. Click **OK**. - -### To install IIS version 6.0 on Windows Server 2003 - -1. From **Manage Your Server**, click **Add or remove a role**, and then click **Next**. - -2. Select **Application server (IIS, ASP.NET)** from the **Server Role** list, and then click **Next**. - -3. Select **Enable ASP.NET** check box, and then click **Next**. - -4. If the summary of selections is correct, click Next. - -### To install IIS version 5.1 on Windows XP with Service Pack 2 and Service Pack 3 installed - -1. In Control Panel, click **Add or Remove Programs**. - -2. In the **Add or Remove Programs** dialog box, click **Add/Remove Windows Components**. - -3. In the **Windows Components Wizard**, select the **Internet Information Services (IIS)** check box, and then click **Next**. - -4. If the **Files Needed** dialog box is displayed, insert your operating system installation disc, browse to the i386 folder, and then click **OK**. - -5. When installation completes, click **Finish**. - -6. Close the **Add or Remove Programs** dialog box, and then close **Control Panel**. - -### To verify the installation of IIS and ASP.NET - -1. Save the HTML file found at the end of this topic in the root \InetPub\wwwroot directory and name it Default.aspx. - -2. Open a browser window. - -3. Type `http://localhost/Default.aspx` in the address box, and then press ENTER. - -4. A Web page with the text "Hello World" should appear. - +To run the samples that are hosted by Internet Information Services (IIS), you must make sure that IIS is properly installed and is running. + +### To install IIS version 7.5 on Windows Server 2008 R2 + +1. From **Server Manager**, select **Roles.** Under **Roles Summary**, click **Add Roles**. + +2. Click **Next** to display the **Select Server Roles** dialog. + +3. Select **Application Server** from the **Roles** list, and then click **Next** twice to display the **Select Role Services** dialog for the Application Server role. + +4. Select the **Web Server (IIS)** check box. If you are prompted to install additional role services and features, click **Add Required Features**. Click **Next** twice to display the **Select Role Services** dialog for the Web Server (IIS) role. + +5. Expand **Management Tools**, and then expand **IIS 6 Management Compatibility**. Select **IIS 6 Scripting Tools**. If you are prompted to install additional role services and features, click **Add Required Role Services**. Click **Next**. + +6. If the summary of selections is correct, click **Install**. + +7. When installation completes, click **Close**. + +### To install IIS version 7.5 on Windows 7 + +1. Click **Start**, and then click **Control Panel**. + +2. Open the **Programs** group. + +3. Under **Programs and Features**, click **Turn Windows Features on or off**. + +4. The **User Account Control** dialog is displayed. Click **Continue**. + +5. The **Windows Features** dialog is displayed. Expand the item labeled **Internet Information Services**. + +6. Expand the item labeled **World Wide Web Services**. + +7. Expand the item labeled **Application Development Features**. + +8. Make sure the following items are selected: + + 1. **.NET Extensibility** + + 2. **ASP.NET** + + 3. **ISAPI Extensions** + + 4. **ISAPI Filters** + +9. Under the item labeled **World Wide Web Services**, expand **Common Http Features**. + +10. Make sure **Static Content** is selected. + +11. Under the item labeled **World Wide Web Services**, expand **Security**. + +12. Make sure that **Windows Authentication** is selected. + +13. Under the **Internet Information Services** directory, expand the item labeled **Web Management Tools**, and then select **IIS Management Console**. + +14. Expand the item labeled **IIS 6 Management Compatibility**, and then select **IIS 6 Scripting Tools**. + +15. Under the **Internet Information Services** directory, expand the item labeled **Microsoft .NET Framework 3.5.1**, and then select **Windows Communication Foundation Http Activation**. + +16. Click **OK**. + +### To install IIS version 7.0 on Windows Server 2008 + +1. From **Server Manager**, select **Roles**. Under **Roles Summary**, click **Add Roles**. + +2. Click **Next** to display the **Select Server Roles** dialog. + +3. Select **Application Server** from the **Roles** list, and then click **Next** twice to display the **Select Role Services** dialog for the Application Server role. + +4. Select **Web Server (IIS)** check box. If you are prompted to install additional role services and features, click **Add Required Features**. Click **Next** twice to display the **Select Role Services** dialog for the Web Server (IIS) role. + +5. Expand **Management Tools**, and then expand **IIS 6 Management Compatibility**. Select **IIS 6 Scripting Tools**. If you are prompted to install additional role services and features, click **Add Required Role Services**. Click **Next**. + +6. If the summary of selections is correct, click **Install**. + +7. When installation completes, click **Close**. + +### To install IIS version 7.0 on Windows Vista + +1. Click Start, and then click Control Panel. + +2. Select the **Programs** group. + +3. Under **Programs and Features**, click **Turn Windows Features on or off**. + +4. The **User Account Control** dialog is displayed. Click **Continue**. + +5. The **Windows Features** dialog is displayed. Expand the item labeled **Internet Information Services**. + +6. Expand the item labeled **World Wide Web Services**. + +7. Expand the item labeled **Application Development Features**. + +8. Make sure the following items are selected: + + 1. **.NET Extensibility** + + 2. **ASP.NET** + + 3. **ISAPI Extensions** + + 4. **ISAPI Filters** + +9. Expand the item labeled **Web Management Tools**, and then select **IIS Management Console**. + +10. Under the item labeled **World Wide Web Services**, expand **Common Http Features**. + +11. Make sure **Static Content** is selected. + +12. Under the item labeled **World Wide Web Services**, expand **Security**. + +13. Make sure **Windows Authentication** is selected. + +14. Expand the item labeled **IIS 6 Management Compatibility**, and then select **IIS 6 Scripting Tools**. + +15. Expand the item labeled **Microsoft .NET Framework 3.0**, and then select **Windows Communication Foundation Http Activation**. + +16. Click **OK**. + +### To install IIS version 6.0 on Windows Server 2003 + +1. From **Manage Your Server**, click **Add or remove a role**, and then click **Next**. + +2. Select **Application server (IIS, ASP.NET)** from the **Server Role** list, and then click **Next**. + +3. Select **Enable ASP.NET** check box, and then click **Next**. + +4. If the summary of selections is correct, click Next. + +### To install IIS version 5.1 on Windows XP with Service Pack 2 and Service Pack 3 installed + +1. In Control Panel, click **Add or Remove Programs**. + +2. In the **Add or Remove Programs** dialog box, click **Add/Remove Windows Components**. + +3. In the **Windows Components Wizard**, select the **Internet Information Services (IIS)** check box, and then click **Next**. + +4. If the **Files Needed** dialog box is displayed, insert your operating system installation disc, browse to the i386 folder, and then click **OK**. + +5. When installation completes, click **Finish**. + +6. Close the **Add or Remove Programs** dialog box, and then close **Control Panel**. + +### To verify the installation of IIS and ASP.NET + +1. Save the HTML file found at the end of this topic in the root \InetPub\wwwroot directory and name it Default.aspx. + +2. Open a browser window. + +3. Type `http://localhost/Default.aspx` in the address box, and then press ENTER. + +4. A Web page with the text "Hello World" should appear. + > [!NOTE] -> Each time you install a new version of the .NET Framework, you must re-register aspnet_isapi as a Web service extension for IIS. To do so, issue the `aspnet_regiis –I –enable` command. - -## Sample Code - -```xml - - -
-

Hello World -

-
- - +> Each time you install a new version of the .NET Framework, you must re-register aspnet_isapi as a Web service extension for IIS. To do so, issue the `aspnet_regiis -I -enable` command. + +## Sample Code + +```xml + + +
+

Hello World +

+
+ + ``` diff --git a/docs/framework/wcf/samples/one-time-setup-procedure-for-the-wcf-samples.md b/docs/framework/wcf/samples/one-time-setup-procedure-for-the-wcf-samples.md index 1c37d2daeae42..dfb70c84576d7 100644 --- a/docs/framework/wcf/samples/one-time-setup-procedure-for-the-wcf-samples.md +++ b/docs/framework/wcf/samples/one-time-setup-procedure-for-the-wcf-samples.md @@ -29,12 +29,12 @@ The **ServiceModelSamples** virtual directory is used for building and running a > If IIS is reinstalled, the following commands will need to be run again. ```console - "%WINDIR%\Microsoft.Net\Framework\v4.0.30319\aspnet_regiis" –i –enable + "%WINDIR%\Microsoft.Net\Framework\v4.0.30319\aspnet_regiis" -i -enable "%WINDIR%\Microsoft.Net\Framework\v4.0.30319\ServiceModelReg.exe" -r ``` > [!WARNING] - > Running the command `aspnet_regiis –i –enable` will make the Default App Pool run using .NET Framework 4, which may produce incompatibility issues for other applications on the same computer. + > Running the command `aspnet_regiis -i -enable` will make the Default App Pool run using .NET Framework 4, which may produce incompatibility issues for other applications on the same computer. 5. Follow the [Firewall Instructions](firewall-instructions.md) for enabling the ports used by the samples. diff --git a/docs/framework/wcf/servicemodelreg-exe.md b/docs/framework/wcf/servicemodelreg-exe.md index dfe804a79bdbe..8e73e1f067852 100644 --- a/docs/framework/wcf/servicemodelreg-exe.md +++ b/docs/framework/wcf/servicemodelreg-exe.md @@ -6,76 +6,76 @@ ms.topic: reference --- # ServiceModel Registration Tool (ServiceModelReg.exe) -This command-line tool provides the ability to manage the registration of WCF and WF components on a single machine. Under normal circumstances you should not need to use this tool as WCF and WF components are configured when installed. But if you are experiencing problems with service activation, you can try to register the components using this tool. - -## Syntax - -```console -ServiceModelReg.exe[(-ia|-ua|-r)|((-i|-u) -c:)] [-v|-q] [-nologo] [-?] -``` - -## Remarks - - The tool can be found in the following location: - - %SystemRoot%\Microsoft.Net\Framework\v3.0\Windows Communication Foundation\ - +This command-line tool provides the ability to manage the registration of WCF and WF components on a single machine. Under normal circumstances you should not need to use this tool as WCF and WF components are configured when installed. But if you are experiencing problems with service activation, you can try to register the components using this tool. + +## Syntax + +```console +ServiceModelReg.exe[(-ia|-ua|-r)|((-i|-u) -c:)] [-v|-q] [-nologo] [-?] +``` + +## Remarks + + The tool can be found in the following location: + + %SystemRoot%\Microsoft.Net\Framework\v3.0\Windows Communication Foundation\ + > [!NOTE] -> When the ServiceModel Registration Tool is run on Windows Vista, the **Windows Features** dialog may not reflect that the **Windows Communication Foundation HTTP Activation** option under **Microsoft .NET Framework 3.0** is turned on. The **Windows Features** dialog can be accessed by clicking **Start**, then click **Run** and then typing **OptionalFeatures**. - - The following tables describe the options that can be used with ServiceModelReg.exe. - -|Option|Description| -|------------|-----------------| -|`-ia`|Installs all WCF and WF components.| -|`-ua`|Uninstalls all WCF and WF components.| -|`-r`|Repairs all WCF and WF components.| -|`-i`|Installs WCF and WF components specified with –c.| -|`-u`|Uninstalls WCF and WF components specified with –c.| -|`-c`|Installs or uninstalls a component:

- httpnamespace – HTTP Namespace Reservation
- tcpportsharing – TCP port sharing service
- tcpactivation – TCP activation service (unsupported on .NET 4 Client Profile)
- namedpipeactivation – Named pipe activation service (unsupported on .NET 4 Client Profile
- msmqactivation – MSMQ activation service (unsupported on .NET 4 Client Profile
- etw – ETW event tracing manifests (Windows Vista or later)| -|`-q`|Quiet mode (only display error logging)| -|`-v`|Verbose mode.| -|`-nologo`|Suppresses the copyright and banner message.| -|`-?`|Displays help text| - -## Fixing the FileLoadException Error - - If you installed previous versions of WCF on your machine, you may get a `FileLoadFoundException` error when you run the ServiceModelReg tool to register a new installation. This can happen even if you have manually removed files from the previous install, but left the machine.config settings intact. - - The error message is similar to the following. - -```console -Error: System.IO.FileLoadException: Could not load file or assembly 'System.ServiceModel, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040) -File name: 'System.ServiceModel, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089' -``` - - You should note from the error message that the System.ServiceModel Version 2.0.0.0 assembly was installed by an early Customer Technology Preview (CTP) release. The current version of the System.ServiceModel assembly released is 3.0.0.0 instead. Therefore, this issue is encountered when you want to install the official WCF release on a machine where an early CTP release of WCF was installed, but not completely uninstalled. - - ServiceModelReg.exe cannot clean up prior version entries, nor can it register the new version's entries. The only workaround is to manually edit machine.config. You can locate this file at the following location. - -```console +> When the ServiceModel Registration Tool is run on Windows Vista, the **Windows Features** dialog may not reflect that the **Windows Communication Foundation HTTP Activation** option under **Microsoft .NET Framework 3.0** is turned on. The **Windows Features** dialog can be accessed by clicking **Start**, then click **Run** and then typing **OptionalFeatures**. + + The following tables describe the options that can be used with ServiceModelReg.exe. + +|Option|Description| +|------------|-----------------| +|`-ia`|Installs all WCF and WF components.| +|`-ua`|Uninstalls all WCF and WF components.| +|`-r`|Repairs all WCF and WF components.| +|`-i`|Installs WCF and WF components specified with -c.| +|`-u`|Uninstalls WCF and WF components specified with -c.| +|`-c`|Installs or uninstalls a component:

- httpnamespace – HTTP Namespace Reservation
- tcpportsharing – TCP port sharing service
- tcpactivation – TCP activation service (unsupported on .NET 4 Client Profile)
- namedpipeactivation – Named pipe activation service (unsupported on .NET 4 Client Profile
- msmqactivation – MSMQ activation service (unsupported on .NET 4 Client Profile
- etw – ETW event tracing manifests (Windows Vista or later)| +|`-q`|Quiet mode (only display error logging)| +|`-v`|Verbose mode.| +|`-nologo`|Suppresses the copyright and banner message.| +|`-?`|Displays help text| + +## Fixing the FileLoadException Error + + If you installed previous versions of WCF on your machine, you may get a `FileLoadFoundException` error when you run the ServiceModelReg tool to register a new installation. This can happen even if you have manually removed files from the previous install, but left the machine.config settings intact. + + The error message is similar to the following. + +```console +Error: System.IO.FileLoadException: Could not load file or assembly 'System.ServiceModel, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040) +File name: 'System.ServiceModel, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089' +``` + + You should note from the error message that the System.ServiceModel Version 2.0.0.0 assembly was installed by an early Customer Technology Preview (CTP) release. The current version of the System.ServiceModel assembly released is 3.0.0.0 instead. Therefore, this issue is encountered when you want to install the official WCF release on a machine where an early CTP release of WCF was installed, but not completely uninstalled. + + ServiceModelReg.exe cannot clean up prior version entries, nor can it register the new version's entries. The only workaround is to manually edit machine.config. You can locate this file at the following location. + +```console %windir%\Microsoft.NET\Framework\v2.0.50727\config\machine.config -``` - - If you are running WCF on a 64-bit machine, you should also edit the same file at this location. - -```console +``` + + If you are running WCF on a 64-bit machine, you should also edit the same file at this location. + +```console %windir%\Microsoft.NET\Framework64\v2.0.50727\config\machine.config -``` - - Locate any XML nodes in this file that refer to "System.ServiceModel, Version=2.0.0.0", delete them and any child nodes. Save the file and re-run ServiceModelReg.exe resolves this problem. - -## Examples - - The following examples show how to use the most common options of the ServiceModelReg.exe tool. - -```console -ServiceModelReg.exe -ia - Installs all components -ServiceModelReg.exe -i -c:httpnamespace -c:etw - Installs HTTP namespace reservation and ETW manifests -ServiceModelReg.exe -u -c:etw - Uninstalls ETW manifests -ServiceModelReg.exe -r - Repairs an extended install +``` + + Locate any XML nodes in this file that refer to "System.ServiceModel, Version=2.0.0.0", delete them and any child nodes. Save the file and re-run ServiceModelReg.exe resolves this problem. + +## Examples + + The following examples show how to use the most common options of the ServiceModelReg.exe tool. + +```console +ServiceModelReg.exe -ia + Installs all components +ServiceModelReg.exe -i -c:httpnamespace -c:etw + Installs HTTP namespace reservation and ETW manifests +ServiceModelReg.exe -u -c:etw + Uninstalls ETW manifests +ServiceModelReg.exe -r + Repairs an extended install ``` diff --git a/docs/framework/wcf/wcf-service-publishing.md b/docs/framework/wcf/wcf-service-publishing.md index 80fb5f4030bcb..ab75ce5ad06df 100644 --- a/docs/framework/wcf/wcf-service-publishing.md +++ b/docs/framework/wcf/wcf-service-publishing.md @@ -1,6 +1,6 @@ --- title: "WCF Service Publishing" -description: WCF Service Publishing helps you deploy your application to a production environment for testing purposes. +description: WCF Service Publishing helps you deploy your application to a production environment for testing purposes. ms.date: "03/30/2017" ms.assetid: c806b253-cd47-4b96-b831-e73cbf08808f --- @@ -42,7 +42,7 @@ Perform the following steps to deploy a service implementation: You can use **Publish** to specify if you want to copy the assembly, configuration, and .svc file for all services defined in the project to the target location, and overwrite existing files at the destination. -If you choose to deploy your application to local IIS, you may encounter errors related to IIS setup. Please ensure that IIS is installed properly. You can enter `http://localhost` in your browser's address bar and check whether the IIS default page displays. In some cases, the issues may also be caused by improper registration of ASP.NET or WCF in IIS. You can open the Developer Command Prompt for Visual Studio and run the command `aspnet_regiis.exe -ir` to fix ASP.NET registration issues, or run command `ServiceModelReg.exe –ia` to fix WCF registration issues. +If you choose to deploy your application to local IIS, you may encounter errors related to IIS setup. Please ensure that IIS is installed properly. You can enter `http://localhost` in your browser's address bar and check whether the IIS default page displays. In some cases, the issues may also be caused by improper registration of ASP.NET or WCF in IIS. You can open the Developer Command Prompt for Visual Studio and run the command `aspnet_regiis.exe -ir` to fix ASP.NET registration issues, or run command `ServiceModelReg.exe -ia` to fix WCF registration issues. ## Files Generated for Publishing diff --git a/docs/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch.md b/docs/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch.md index b841dac487803..222cb7292e582 100644 --- a/docs/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch.md +++ b/docs/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch.md @@ -23,7 +23,7 @@ The `CreateFlowchartWithFaults` activity uses a . So, the discount calculation is wrapped in a activity that catches the exception and sets the discount to zero.| +|MWK|15 + (1 - 1/`numberOfKids`)\*10 **Note:** Potentially, this calculation can throw a . So, the discount calculation is wrapped in a activity that catches the exception and sets the discount to zero.| ## To use this sample diff --git a/docs/framework/windows-workflow-foundation/workflow-tracing.md b/docs/framework/windows-workflow-foundation/workflow-tracing.md index cca49d9b6b358..0f43b045337b0 100644 --- a/docs/framework/windows-workflow-foundation/workflow-tracing.md +++ b/docs/framework/windows-workflow-foundation/workflow-tracing.md @@ -6,67 +6,67 @@ ms.assetid: 18737989-0502-4367-b5f6-617ebfb77c96 --- # Workflow Tracing -Workflow tracing offers a way to capture diagnostic information using .NET Framework trace listeners. Tracing can be enabled if a problem is detected with the application and then disabled again once the problem is resolved. There are two ways you could enable debug tracing for workflows. You can configure it using the Event Trace viewer or you can use to send trace events to a file. - -## Enabling Debug Tracing in ETW - - To enable tracing using ETW, enable the Debug channel in Event Viewer: - -1. Navigate to analytic and debug logs node in Event Viewer. - -2. In the tree view in Event Viewer, navigate to **Event Viewer->Applications and Services Logs->Microsoft->Windows->Application Server-Applications**. Right-click **Application Server-Applications** and select **View->Show Analytic and Debug Logs**. Right-click **Debug** and select **Enable Log**. - -3. When a workflow runs the debug and traces are emitted to ETW debug channel, they can be viewed in the Event Viewer. Navigate to **Event Viewer->Applications and Services Logs->Microsoft->Windows->Application Server-Applications**. Right-click **Debug** and select **Refresh**. - -4. The default analytic trace buffer size is only 4 kilobytes (KB); it is recommended to increase the size to 32 KB. To do this, perform the following steps. - - 1. Execute the following command in the current framework directory (for example, C:\Windows\Microsoft.NET\Framework\v4.0.21203): `wevtutil um Microsoft.Windows.ApplicationServer.Applications.man` - - 2. Change the \ value in the Windows.ApplicationServer.Applications.man file to 32. - - ```xml - - - 32 - - - ``` - - 3. Execute the following command in the current framework directory (for example, C:\Windows\Microsoft.NET\Framework\v4.0.21203): `wevtutil im Microsoft.Windows.ApplicationServer.Applications.man` - +Workflow tracing offers a way to capture diagnostic information using .NET Framework trace listeners. Tracing can be enabled if a problem is detected with the application and then disabled again once the problem is resolved. There are two ways you could enable debug tracing for workflows. You can configure it using the Event Trace viewer or you can use to send trace events to a file. + +## Enabling Debug Tracing in ETW + + To enable tracing using ETW, enable the Debug channel in Event Viewer: + +1. Navigate to analytic and debug logs node in Event Viewer. + +2. In the tree view in Event Viewer, navigate to **Event Viewer->Applications and Services Logs->Microsoft->Windows->Application Server-Applications**. Right-click **Application Server-Applications** and select **View->Show Analytic and Debug Logs**. Right-click **Debug** and select **Enable Log**. + +3. When a workflow runs the debug and traces are emitted to ETW debug channel, they can be viewed in the Event Viewer. Navigate to **Event Viewer->Applications and Services Logs->Microsoft->Windows->Application Server-Applications**. Right-click **Debug** and select **Refresh**. + +4. The default analytic trace buffer size is only 4 kilobytes (KB); it is recommended to increase the size to 32 KB. To do this, perform the following steps. + + 1. Execute the following command in the current framework directory (for example, C:\Windows\Microsoft.NET\Framework\v4.0.21203): `wevtutil um Microsoft.Windows.ApplicationServer.Applications.man` + + 2. Change the \ value in the Windows.ApplicationServer.Applications.man file to 32. + + ```xml + + + 32 + + + ``` + + 3. Execute the following command in the current framework directory (for example, C:\Windows\Microsoft.NET\Framework\v4.0.21203): `wevtutil im Microsoft.Windows.ApplicationServer.Applications.man` + > [!NOTE] -> If you are using the .NET Framework 4 Client Profile, you must first register the ETW manifest by running the following command from the .NET Framework 4 directory: `ServiceModelReg.exe –i –c:etw` - -## Enabling Debug Tracing using System.Diagnostics - - These listeners can be configured in the App.config file of the workflow application, or the Web.config for a workflow service. In this example, a is configured to save tracing information to the MyTraceLog.txt file in the current directory. - -```xml - - - - - - - - - - - - - - - - - - - - -``` - +> If you are using the .NET Framework 4 Client Profile, you must first register the ETW manifest by running the following command from the .NET Framework 4 directory: `ServiceModelReg.exe -i -c:etw` + +## Enabling Debug Tracing using System.Diagnostics + + These listeners can be configured in the App.config file of the workflow application, or the Web.config for a workflow service. In this example, a is configured to save tracing information to the MyTraceLog.txt file in the current directory. + +```xml + + + + + + + + + + + + + + + + + + + + +``` + ## See also - [Windows Server App Fabric Monitoring](/previous-versions/appfabric/ee677251(v=azure.10)) diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 639decc0c8367..ff1cadc83aa13 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -194,6 +194,8 @@ items: href: ../../core/tools/dotnet-package-update.md - name: dotnet publish href: ../../core/tools/dotnet-publish.md + - name: dotnet project convert + href: ../../core/tools/dotnet-project-convert.md - name: dotnet reference add/list/remove items: - name: dotnet reference add