diff --git a/aspnetcore/fundamentals/error-handling.md b/aspnetcore/fundamentals/error-handling.md index 06597bac65a7..bf2a61b8f549 100644 --- a/aspnetcore/fundamentals/error-handling.md +++ b/aspnetcore/fundamentals/error-handling.md @@ -302,7 +302,7 @@ An alternative approach to using , which writes to the response stream and therefore prevents the custom problem response from being returned. diff --git a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md index 33bacf2f0669..fbedc9008b79 100644 --- a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md +++ b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md @@ -73,6 +73,8 @@ Launch the app and navigate to `https://localhost:/openapi/v1.json` to vie ## Including OpenAPI metadata in an ASP.NET web app +### Including OpenAPI metadata for endpoints + ASP.NET collects metadata from the web app's endpoints and uses it to generate an OpenAPI document. In controller-based apps, metadata is collected from attributes like `[EndpointDescription]`, `[HttpPost]`, and `[Produces]`. @@ -96,7 +98,7 @@ ASP.NET Core does not collect metadata from XML doc comments. The following sections demonstrate how to include metadata in an app to customize the generated OpenAPI document. -### Summary and description +#### Summary and description The endpoint summary and description can be set using the `[EndpointSummary]` and `[EndpointDescription]` attributes, or in minimal APIs, using the `WithSummary` and `WithDescription` extension methods. @@ -106,7 +108,7 @@ or in minimal APIs, using the `WithSummary` and `WithDescription` extension meth * `WithSummary`: * `WithDescription`: -#### [Minimal APIs](#tab/minimal-apis) +##### [Minimal APIs](#tab/minimal-apis) The following sample demonstrates the different strategies for setting summaries and descriptions. @@ -123,7 +125,7 @@ app.MapGet("/attributes", () => "Hello world!"); ``` -#### [Controllers](#tab/controllers) +##### [Controllers](#tab/controllers) The following sample demonstrates how to set summaries and descriptions. @@ -138,7 +140,7 @@ The following sample demonstrates how to set summaries and descriptions. ``` --- -### tags +#### tags OpenAPI supports specifying tags on each endpoint as a form of categorization. In controller-based apps, the controller name is automatically added as a tag on each of its endpoints, @@ -148,7 +150,7 @@ In minimal APIs, tags can be set using either the `[Tags]` attribute or the `Wit * `[Tags]`: * `WithTags`: -#### [Minimal APIs](#tab/minimal-apis) +##### [Minimal APIs](#tab/minimal-apis) The following sample demonstrates the different strategies for setting tags. @@ -161,7 +163,7 @@ app.MapGet("/attributes", () => "Hello world!"); ``` -#### [Controllers](#tab/controllers) +##### [Controllers](#tab/controllers) The following sample demonstrates how to set tags. @@ -175,7 +177,7 @@ The following sample demonstrates how to set tags. ``` --- -### operationId +#### operationId OpenAPI supports an operationId on each endpoint as a unique identifier or name for the operation. In controller-based apps, the operationId can be set using the `[EndpointName]` attribute. @@ -184,7 +186,7 @@ In minimal APIs, the operationId can be set using either the `[EndpointName]` at * `[EndpointName]`: * `WithName`: -#### [Minimal APIs](#tab/minimal-apis) +##### [Minimal APIs](#tab/minimal-apis) The following sample demonstrates the different strategies for setting the operationId. @@ -197,7 +199,7 @@ app.MapGet("/attributes", () => "Hello world!"); ``` -#### [Controllers](#tab/controllers) +##### [Controllers](#tab/controllers) The following sample demonstrates how to set the operationId. @@ -211,7 +213,7 @@ The following sample demonstrates how to set the operationId. ``` --- -### parameters +#### parameters OpenAPI supports annotating path, query string, header, and cookie parameters that are consumed by an API. @@ -221,7 +223,7 @@ The `[Description]` attribute can be used to provide a description for a paramet * [`Description`](/dotnet/api/system.componentmodel.descriptionattribute) -#### [Minimal APIs](#tab/minimal-apis) +##### [Minimal APIs](#tab/minimal-apis) The follow sample demonstrates how to set a description for a parameter. @@ -230,7 +232,7 @@ app.MapGet("/attributes", ([Description("This is a description.")] string name) => "Hello world!"); ``` -#### [Controllers](#tab/controllers) +##### [Controllers](#tab/controllers) The following sample demonstrates how to set a description for a parameter. @@ -243,7 +245,7 @@ The following sample demonstrates how to set a description for a parameter. ``` --- -### requestBody +#### requestBody @@ -275,7 +277,7 @@ When no explicit annotation is provided, the framework attempts to determine the * All other request body parameters are described with the `application/json` content-type. * The request body is treated as optional if it's nullable or if the property is set on the [`FromBody`](xref:Microsoft.AspNetCore.Mvc.FromBodyAttribute) attribute. -### Describe response types +#### Describe response types @@ -302,13 +304,13 @@ app.MapGet("/todos", async (TodoDb db) => }); ``` -#### Set responses for `ProblemDetails` +##### Set responses for `ProblemDetails` When setting the response type for endpoints that may return a ProblemDetails response, the or extension method or can be used to add the appropriate annotation to the endpoint's metadata. When there are no explicit annotations provided by one of these strategies, the framework attempts to determine a default response type by examining the signature of the response. This default response is populated under the `200` status code in the OpenAPI definition. -#### Multiple response types +##### Multiple response types If an endpoint can return different response types in different scenarios, you can provide metadata in the following ways: @@ -324,7 +326,7 @@ If an endpoint can return different response types in different scenarios, you c The union types implement implicit cast operators. These operators enable the compiler to automatically convert the types specified in the generic arguments to an instance of the union type. This capability has the added benefit of providing compile-time checking that a route handler only returns the results that it declares it does. Attempting to return a type that isn't declared as one of the generic arguments to `Results` results in a compilation error. -### Excluding endpoints from the generated document +#### Excluding endpoints from the generated document @@ -344,7 +346,7 @@ app.MapGet("/attributes", () => "Hello world!"); ``` -## Including OpenAPI metadata for data types +### Including OpenAPI metadata for data types C# classes or records used in request or response bodies are represented as schemas in the generated OpenAPI document. @@ -357,7 +359,7 @@ of the class or record property name. The can be used on an individual property to specify the name of the property in the schema. -## type and format +#### type and format The JSON Schema library maps standard C# types to OpenAPI `type` and `format` as follows: @@ -386,7 +388,7 @@ Note that object and dynamic types have _no_ type defined in the OpenAPI because The `type` and `format` can also be set with a [Schema Transformer](#use-schema-transformers). For example, you may want the `format` of decimal types to be `decimal` instead of `double`. -## Using attributes to add metadata +#### Using attributes to add metadata ASP.NET uses metadata from attributes on class or record properties to set metadata on the corresponding properties of the generated schema. @@ -404,30 +406,30 @@ The following table summarizes attributes from the `System.ComponentModel` names Note that in controller-based apps, these attributes add filters to the operation to validate that any incoming data satisfies the constraints. In Minimal APIs, these attributes set the metadata in the generated schema but validation must be performed explicitly via an endpoint filter, in the route handler's logic, or via a third-party package. -## Other sources of metadata for generated schemas +#### Other sources of metadata for generated schemas -### required +##### required Properties can also be marked as `required` with the [required](/dotnet/csharp/language-reference/proposals/csharp-11.0/required-members#required-modifier) modifier. -### enum +##### enum Enum types in C# are integer-based, but can be represented as strings in JSON with a and a . When an enum type is represented as a string in JSON, the generated schema will have an `enum` property with the string values of the enum. An enum type without a will be defined as `type: integer` in the generated schema. **Note:** The does not set the `enum` values of a property. -### nullable +##### nullable Properties defined as a nullable value or reference type have `nullable: true` in the generated schema. This is consistent with the default behavior of the deserializer, which accepts `null` as a valid value for a nullable property. -### additionalProperties +##### additionalProperties Schemas are generated without an `additionalProperties` assertion by default, which implies the default of `true`. This is consistent with the default behavior of the deserializer, which silently ignores additional properties in a JSON object. If the additional properties of a schema should only have values of a specific type, define the property or class as a `Dictionary`. The key type for the dictionary must be `string`. This generates a schema with `additionalProperties` specifying the schema for "type" as the required value types. -### Metadata for polymorphic types +##### Metadata for polymorphic types Use the and attributes on a parent class to to specify the discriminator field and subtypes for a polymorphic type. @@ -435,7 +437,7 @@ The adds the disc An abstract class with a attribute has a `discriminator` field in the schema, but a concrete class with a attribute doesn't have a `discriminator` field. OpenAPI requires that the discriminator property be a required property in the schema, but since the discriminator property isn't defined in the concrete base class, the schema cannot include a `discriminator` field. -## Adding metadata with a schema transformer +#### Adding metadata with a schema transformer A schema transformer can be used to override any default metadata or add additional metadata, such as `example` values, to the generated schema. See [Use schema transformers](#use-schema-transformers) for more information. diff --git a/aspnetcore/includes/managed-identities-test-non-production.md b/aspnetcore/includes/managed-identities-test-non-production.md index 7e509d3eed7f..28cdc85076ae 100644 --- a/aspnetcore/includes/managed-identities-test-non-production.md +++ b/aspnetcore/includes/managed-identities-test-non-production.md @@ -4,5 +4,5 @@ ms.author: wpickett ms.date: 08/22/2024 ms.topic: include --- -> [!NOTE] +> [!WARNING] > This article uses a local database that doesn't require the user to be authenticated. Production apps should use the most secure authentication flow available. For more information on authentication for deployed test and production apps, see [Secure authentication flows](xref:security/index#secure-authentication-flows). diff --git a/aspnetcore/security/app-secrets.md b/aspnetcore/security/app-secrets.md index 37adcb17e4bc..e1a0a0e9e76b 100644 --- a/aspnetcore/security/app-secrets.md +++ b/aspnetcore/security/app-secrets.md @@ -60,7 +60,7 @@ File system path: In the preceding file paths, replace `` with the `UserSecretsId` value specified in the project file. -Don't write code that depends on the location or format of data saved with the Secret Manager tool. These implementation details may change. For example, the secret values aren't encrypted, but could be in the future. +Don't write code that depends on the location or format of data saved with the Secret Manager tool. These implementation details may change. For example, the secret values aren't encrypted. ## Enable secret storage diff --git a/aspnetcore/security/authorization/secure-data.md b/aspnetcore/security/authorization/secure-data.md index 97a94b1317b6..53cb0d3aabe4 100644 --- a/aspnetcore/security/authorization/secure-data.md +++ b/aspnetcore/security/authorization/secure-data.md @@ -137,7 +137,7 @@ The `SeedData` class creates two accounts: administrator and manager. Use the [S dotnet user-secrets set SeedUserPW ``` -If a strong password is not specified, an exception is thrown when `SeedData.Initialize` is called. +If a weak password is specified, an exception is thrown when `SeedData.Initialize` is called. Update the app to use the test password: @@ -288,9 +288,12 @@ In the preceding code: ## Test the completed app +> [!WARNING] +> This article uses the [Secret Manager tool](xref:security/app-secrets) to store the password for the seeded user accounts. The Secret Manager tool is used to store sensitive data during local development. For more information on authentication for deployed test and production apps, see [Secure authentication flows](xref:security/index#secure-authentication-flows). + If you haven't already set a password for seeded user accounts, use the [Secret Manager tool](xref:security/app-secrets#secret-manager) to set a password: -* Choose a strong password: Use eight or more characters and at least one upper-case character, number, and symbol. For example, `Passw0rd!` meets the strong password requirements. +* Choose a strong password: Use eight or more characters and at least one upper-case character, number, and symbol. * Execute the following command from the project's folder, where `` is the password: ```dotnetcli diff --git a/aspnetcore/security/cors.md b/aspnetcore/security/cors.md index a9283547be59..d27cc7ce1a64 100644 --- a/aspnetcore/security/cors.md +++ b/aspnetcore/security/cors.md @@ -220,11 +220,11 @@ This section describes the various options that can be set in a CORS policy: ### Set the allowed request headers -To allow specific headers to be sent in a CORS request, called [author request headers](https://xhr.spec.whatwg.org/#request), call and specify the allowed headers: +To allow specific headers to be sent in a CORS request, called *author request headers*, call and specify the allowed headers: [!code-csharp[](~/security/cors/8.0sample/Cors/Web2API/Program.cs?name=snippet_sa)] -To allow all [author request headers](https://www.w3.org/TR/cors/#author-request-headers), call : +To allow all author request headers, call : [!code-csharp[](~/security/cors/8.0sample/Cors/Web2API/Program.cs?name=snippet_aah)] @@ -321,7 +321,7 @@ For some CORS requests, the browser sends an additional [OPTIONS](https://develo * `multipart/form-data` * `text/plain` -The rule on request headers set for the client request applies to headers that the app sets by calling `setRequestHeader` on the `XMLHttpRequest` object. The CORS specification calls these headers [author request headers](https://www.w3.org/TR/cors/#author-request-headers). The rule doesn't apply to headers the browser can set, such as `User-Agent`, `Host`, or `Content-Length`. +The rule on request headers set for the client request applies to headers that the app sets by calling `setRequestHeader` on the `XMLHttpRequest` object. The CORS specification calls these headers *author request headers*. The rule doesn't apply to headers the browser can set, such as `User-Agent`, `Host`, or `Content-Length`. > [!NOTE] > This article contains URLs created by deploying the [sample code](https://github.com/dotnet/AspNetCore.Docs/tree/live/aspnetcore/security/cors/8.0sample/Cors) to two Azure web sites, `https://cors3.azurewebsites.net` and `https://cors.azurewebsites.net`. @@ -360,7 +360,6 @@ The preflight request uses the [HTTP OPTIONS](https://developer.mozilla.org/docs * [Access-Control-Request-Method](https://developer.mozilla.org/docs/Web/HTTP/Headers/Access-Control-Request-Method): The HTTP method that will be used for the actual request. * [Access-Control-Request-Headers](https://developer.mozilla.org/docs/Web/HTTP/Headers/Access-Control-Allow-Headers): A list of request headers that the app sets on the actual request. As stated earlier, this doesn't include headers that the browser sets, such as `User-Agent`. -* [Access-Control-Allow-Methods](https://developer.mozilla.org/docs/Web/HTTP/Headers/Access-Control-Allow-Methods) If the preflight request is denied, the app returns a `200 OK` response but doesn't set the CORS headers. Therefore, the browser doesn't attempt the cross-origin request. For an example of a denied preflight request, see the [Test CORS](#testc6) section of this document. @@ -373,7 +372,7 @@ To allow specific headers, call : +To allow all author request headers, call : [!code-csharp[](~/security/cors/8.0sample/Cors/Web2API/Program.cs?name=snippet_aah2)]