diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000000..d0262c28f9a --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,174 @@ +# .NET Core Repository (dotnet/core) + +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. + +This is the official .NET release notes and announcements repository. It is NOT a buildable codebase repository - it contains documentation, release notes, and metadata about .NET releases. You do not build applications here; you maintain release documentation and validate content. + +## Working Effectively + +### Initial Setup + +Set up the validation tools needed for this documentation repository: + +```bash +npm install markdownlint-cli markdown-link-check prettier +pip install checkov +``` + +### Validation Commands + +Always run these validation commands before committing changes. All commands have been tested and work correctly: + +1. **Markdown linting** (takes ~1 second): + + ```bash + npx markdownlint --config .github/linters/.markdown-lint.yml *.md + npx markdownlint --config .github/linters/.markdown-lint.yml release-notes/**/*.md + ``` + +2. **Link checking** (takes 30-180 seconds depending on external links - NEVER CANCEL): + + ```bash + npx markdown-link-check --config .github/workflows/markdown-link-check-config.json README.md + npx markdown-link-check --config .github/workflows/markdown-link-check-config.json [specific-file].md + ``` + + TIMEOUT WARNING: Set timeout to 5+ minutes for link checking. External links may be slow or blocked by network restrictions. + +3. **Security scanning with checkov** (takes ~38 seconds): + + ```bash + checkov --config-file .checkov.yml --directory . --quiet + ``` + +4. **Format checking with prettier** (takes ~5 seconds): + + ```bash + npx prettier --check --ignore-path .prettierignore . + ``` + + Note: This will show format warnings for most files but will not fail. Format fixing is typically not required unless specifically requested. + +### Git Operations + +Standard git workflow for documentation changes: + +```bash +git --no-pager status +git --no-pager diff +git add [specific-files] +git commit -m "Descriptive commit message" +git push origin [branch-name] +``` + +## Repository Structure + +### Key Directories + +- `/release-notes/` - Version-specific release notes organized by major version (8.0/, 9.0/, 10.0/, etc.) + - Each version has `releases.json`, `supported-os.json`, and markdown files for specific releases + - `/release-notes/schemas/` - JSON schemas for release metadata + - `/release-notes/templates/` - Templates for new release notes +- `/Documentation/` - General documentation about .NET Core ecosystem and policies +- `/.github/workflows/` - GitHub Actions for validation (super-linter, markdown-link-check, etc.) +- Root level - Policy documents, README, CONTRIBUTING, and support information + +### Important Files + +- `README.md` - Main repository landing page with current release information +- `releases.md` - Release schedule and support information +- `release-policies.md` - .NET release and support policies +- `release-notes/releases-index.json` - Master index of all .NET releases +- `CONTRIBUTING.md` - Links to actual contribution guidelines in dotnet/runtime + +## Common Tasks + +### Adding New Release Notes + +1. Navigate to appropriate version directory in `/release-notes/[version]/` +2. Create new markdown file following existing naming convention (e.g., `9.0.8.md`) +3. Update `releases.json` with new release metadata +4. Update root `README.md` if this is a latest patch version +5. Run all validation commands +6. Check that links work and markdown is properly formatted + +### Updating Release Metadata + +Release metadata is stored in JSON files: + +- `release-notes/releases-index.json` - Master index +- `release-notes/[version]/releases.json` - Version-specific releases +- `release-notes/[version]/supported-os.json` - Supported operating systems + +Always validate JSON syntax and schema compliance after edits. + +### Updating Documentation + +1. Edit markdown files in `/Documentation/` or root level +2. Run markdown linting: `npx markdownlint --config .github/linters/.markdown-lint.yml [file]` +3. Check links: `npx markdown-link-check --config .github/workflows/markdown-link-check-config.json [file]` +4. Verify changes don't break existing navigation or references + +## Validation Requirements + +### Before Every Commit + +Always run these validation steps in order: + +1. Markdown linting (must pass without errors) +2. Link checking (external links may fail due to network restrictions - this is acceptable) +3. Security scanning with checkov (must pass) +4. Format checking (warnings are acceptable) + +### Manual Validation Scenarios + +Since this is a documentation repository, manual validation involves: + +1. **Link verification**: Navigate to updated pages and verify internal links work +2. **Content accuracy**: Ensure release notes match actual .NET releases +3. **JSON schema validation**: Ensure metadata files follow required schema +4. **Cross-reference checking**: Verify links between release notes and main README are consistent + +### CI/CD Integration + +The repository uses GitHub Actions workflows: + +- `.github/workflows/super-linter.yml` - Runs comprehensive linting +- `.github/workflows/markdown-link-check.yml` - Validates markdown links +- All other workflow files are for issue/PR labeling automation + +## Timing Expectations + +| Command | Expected Time | Timeout Setting | +| --------------------- | -------------- | --------------- | +| markdownlint | 1 second | 30 seconds | +| markdown-link-check | 30-180 seconds | 5+ minutes | +| checkov security scan | 38 seconds | 2 minutes | +| prettier format check | 5 seconds | 30 seconds | + +NEVER CANCEL these commands early. Network-dependent operations like link checking may take longer than expected. + +## Troubleshooting + +### Common Issues + +1. **JSON syntax errors**: Use a JSON validator before committing changes to .json files +2. **Broken internal links**: Verify relative paths are correct and files exist +3. **External link failures**: These are often due to network restrictions and may be acceptable +4. **Markdown formatting**: Follow existing patterns in similar files +5. **Schema validation failures**: Ensure JSON metadata follows schemas in `/release-notes/schemas/` + +### Network Restrictions + +Some external links may fail during link checking due to network restrictions in CI environments. This is expected and acceptable as long as internal links work correctly. + +## Related Repositories + +This repository links to many other .NET repositories: + +- `dotnet/runtime` - Core .NET runtime and libraries +- `dotnet/sdk` - .NET SDK +- `dotnet/aspnetcore` - ASP.NET Core +- See `Documentation/core-repos.md` for complete list + +Do not attempt to build, run, or test code here. This repository contains only documentation and metadata about the .NET ecosystem. diff --git a/.github/workflows/markdown-link-check-config.json b/.github/workflows/markdown-link-check-config.json index 1fc9cdc7921..8d9aa91f314 100644 --- a/.github/workflows/markdown-link-check-config.json +++ b/.github/workflows/markdown-link-check-config.json @@ -1,11 +1,11 @@ -{ - "ignorePatterns": [ - { - "pattern": "^http://localhost" - }, - { - "pattern": "^release-notes/templates/" // ignore links in docs directory - } - ], - "aliveStatusCodes": [429, 200] -} +{ + "ignorePatterns": [ + { + "pattern": "^http://localhost" + }, + { + "pattern": "^release-notes/templates/" + } + ], + "aliveStatusCodes": [429, 200] +} diff --git a/.gitignore b/.gitignore index c3e31e39139..5bbb800fddc 100644 --- a/.gitignore +++ b/.gitignore @@ -42,3 +42,8 @@ bld/ msbuild.log msbuild.err msbuild.wrn + +# Node.js build artifacts +node_modules/ +package-lock.json +package.json diff --git a/release-notes/10.0/README.md b/release-notes/10.0/README.md index 20de4508bb8..20963e2ee07 100644 --- a/release-notes/10.0/README.md +++ b/release-notes/10.0/README.md @@ -16,6 +16,7 @@ It is currently in development and not supported. .NET 10 is expected to be rele | Date | Release | | :-- | :-- | +| 2025/09/10 | [10.0.0 RC 1](preview/rc1/README.md) | | 2025/08/12 | [10.0.0 Preview 7](preview/preview7/README.md) | | 2025/07/15 | [10.0.0 Preview 6](preview/preview6/README.md) | | 2025/06/10 | [10.0.0 Preview 5](preview/preview5/README.md) | @@ -71,6 +72,7 @@ It is currently in development and not supported. .NET 10 is expected to be rele ### ASP.NET Core - [What's new in ASP.NET Core 10.0](https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-10.0) +- [RC 1](preview/rc1/aspnetcore.md) - [Preview 7](preview/preview7/aspnetcore.md) - [Preview 6](preview/preview6/aspnetcore.md) - [Preview 5](preview/preview5/aspnetcore.md) diff --git a/release-notes/10.0/preview/rc1/README.md b/release-notes/10.0/preview/rc1/README.md new file mode 100644 index 00000000000..3630ae536f0 --- /dev/null +++ b/release-notes/10.0/preview/rc1/README.md @@ -0,0 +1,40 @@ +# .NET 10 Release Candidate 1 - Release Notes + +.NET 10 Release Candidate 1 released on September 10, 2025. Find more information on new features released in .NET 10 Release Candidate 1 by browsing through the release notes below: + +- [Libraries](./libraries.md) +- [Runtime](./runtime.md) +- [SDK](./sdk.md) + +## Languages + +- [C#](./csharp.md) +- [F#](./fsharp.md) +- [Visual Basic](./visualbasic.md) + +## Workloads, Libraries, & More + +- [.NET MAUI](./dotnetmaui.md) +- [ASP.NET Core](./aspnetcore.md) +- [Container images](./containers.md) +- [EF Core & Data](./efcore.md) +- [Windows Forms](./winforms.md) +- [WPF](./wpf.md) + +## Get Started + +Instructions on getting started with .NET 10 can be found in the [getting started guide](../../get-started.md). Installers and binaries for .NET 10 Release Candidate 1 can be found [here on GitHub](./10.0.0-rc.1.md). + +## Stay up-to-date + +You can find a detailed overview of all new features in .NET 10: + +- [What's new in .NET 10](https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10/overview) +- [What's new in C# 14](https://learn.microsoft.com/dotnet/csharp/whats-new/csharp-14) +- [What's new in .NET MAUI](https://learn.microsoft.com/dotnet/maui/whats-new/dotnet-10) +- [What's new in ASP.NET Core](https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-10.0) +- [What's new in Entity Framework Core](https://learn.microsoft.com/ef/core/what-is-new/ef-core-10.0/whatsnew) +- [What's new in Windows Forms](https://learn.microsoft.com/dotnet/desktop/winforms/whats-new/net100) +- [What's new in WPF](https://learn.microsoft.com/dotnet/desktop/wpf/whats-new/net100) + +The latest .NET 10 release is always available at [dotnet.microsoft.com](https://dotnet.microsoft.com/download/dotnet/10.0) and [.NET 10 Releases](../../README.md). diff --git a/release-notes/10.0/preview/rc1/aspnetcore.md b/release-notes/10.0/preview/rc1/aspnetcore.md new file mode 100644 index 00000000000..a07550c5fd5 --- /dev/null +++ b/release-notes/10.0/preview/rc1/aspnetcore.md @@ -0,0 +1,172 @@ +# ASP.NET Core updates in .NET 10 Release Candidate 1 + +Here's a summary of what's new in ASP.NET Core in this release: + +* [New ASP.NET Core Identity metrics](#new-aspnet-core-identity-metrics) +* [Validation improvements for Blazor and Minimal APIs](#validation-improvements-for-blazor-and-minimal-apis) +* [OpenAPI schema generation improvements](#openapi-schema-generation-improvements) + +ASP.NET Core updates in .NET 10 Release Candidate 1: + +* [Release notes](aspnetcore.md) +* [What's new in ASP.NET Core in .NET 10](https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-10.0) documentation. +* [Breaking changes](https://docs.microsoft.com/dotnet/core/compatibility/10.0#aspnet-core) +* [Roadmap](https://aka.ms/aspnet/roadmap) + +.NET 10 Release Candidate 1: + +* [Discussion](https://aka.ms/dotnet/10/rc1) +* [Release notes](README.md) + +## New ASP.NET Core Identity metrics + +[ASP.NET Core Identity](https://learn.microsoft.com/aspnet/core/security/authentication/identity) observability has been improved in .NET 10 with metrics. Metrics are counters, histograms and gauges that provide time-series measurements of system or application behavior. + +You can use the new ASP.NET Core Identity metrics to observe user management, such as new user creations, password changes and role assignments. You can also use the metrics to observe login/session handling, such as login attempts, sign ins and sign outs, and users using two factor authentication. + +The new metrics are in the `Microsoft.AspNetCore.Identity` meter: + +* `aspnetcore.identity.user.create.duration` +* `aspnetcore.identity.user.update.duration` +* `aspnetcore.identity.user.delete.duration` +* `aspnetcore.identity.user.check_password_attempts` +* `aspnetcore.identity.user.generated_tokens` +* `aspnetcore.identity.user.verify_token_attempts` +* `aspnetcore.identity.sign_in.authenticate.duration` +* `aspnetcore.identity.sign_in.check_password_attempts` +* `aspnetcore.identity.sign_in.sign_ins` +* `aspnetcore.identity.sign_in.sign_outs` +* `aspnetcore.identity.sign_in.two_factor_clients_remembered` +* `aspnetcore.identity.sign_in.two_factor_clients_forgotten` + +For more information about using metrics in ASP.NET Core, see [ASP.NET Core metrics](https://learn.microsoft.com/aspnet/core/log-mon/metrics/metrics). + +## Validation improvements for Blazor and Minimal APIs + +Several features and fixes have been added to the new validation API that is coming in .NET 10 for Minimal APIs and Blazor. The RC1 updates are focused on providing feature parity and behavioral compatibility with the existing `System.ComponentModel.DataAnnotations.Validator`. + +### Type-level validation attributes + +The new validations now support attributes placed on classes and records themselves. + +```csharp +[SumLimit(42)] +record Point(int X, int Y); + +class SumLimitAttribute(int Limit) : ValidationAttribute +{ + protected override ValidationResult? IsValid(object? value, ValidationContext _) + { + if (value is Point point && point.X + point.Y > Limit) + { + return new ValidationResult("The sum of X and Y is too high"); + } + return ValidationResult.Success; + } +} +``` + +### Skipping validation + +A new `[SkipValidation]` attribute can be used to omit selected properties, parameters, or types from validation. When applied to a property or a method parameter, the validator skips that value during validation. When applied to a type, the validator skips all properties and parameters of that type. + +This can be useful, in particular, when using the same model types in cases which require and do not require validation. + +```csharp +class Order +{ + public Address PaymentAddress { get; set; } + + [SkipValidation] + public Address ContactAddress { get; set; } + + // ... +} + +class Address +{ + [Required] + public string Street { get; set; } + + // ... +} +``` + +Additionally, properties annotated with the `[JsonIgnore]` attribute are now also omitted from validation to improve consistency between serialization and validation in the context of JSON models. Note that the `[SkipValidation]` attribute should be preferred in general cases. + +### Backwards-compatible behavior + +Type validation logic has been updated to match the behavior of `System.ComponentModel.DataAnnotations.Validator` with regards to order of validations and short-circuiting. This means that the following rules are applied when validating an instance of type `T`: + +1. Member properties of `T` are validated, including recursively validating nested objects. +2. Type-level attributes of `T` are validated. +3. The `IValidatableObject.Validate` method is executed, if `T` implements it. + +In case one of these steps produces a validation error, the following steps are skipped. + +## OpenAPI schema generation improvements + +Several OpenAPI schema generation improvements have been made in .NET 10 RC1. + +### Model nullable types using oneOf in OpenAPI schema + +OpenAPI schema generation for nullable types was improved by using the `oneOf` pattern instead of the nullable property for complex types and collections. The implementation: + +* Uses `oneOf` with `null` and the actual type schema for nullable complex types in request/response schemas +* Implements proper nullability detection for parameters, properties, and return types using reflection and NullabilityInfoContext +* Prunes null types from componentized schemas to avoid duplication + +### Fixes/improvements to schema reference resolution + +This release improves the handling of JSON schemas for OpenAPI document generation by properly resolving relative JSON schema references (`$ref`) in the root schema document. + +### Include property descriptions as siblings of $ref in OpenAPI schema + +Prior to .NET 10, ASP.NET Core discarded descriptions on properties that were defined with `$ref` in the generated OpenAPI document. This was necessary because OpenAPI v3.0 did not allow sibling properties alongside `$ref` in schema definitions. But this restriction has been relaxed in OpenAPI 3.1, allowing descriptions to be included alongside `$ref`. Support was added in RC1 to include property descriptions as siblings of `$ref` in the generated OpenAPI schema. + +Thank you [@desjoerd](https://github.com/desjoerd) for this contribution! + +### Add metadata from XML comments on `[AsParameters]` types to OpenAPI schema + +Support has been added for processing XML comments on properties of `[AsParameters]` parameter classes to extract metadata for use in OpenAPI documentation generation. + +### Exclude unknown HTTP methods from OpenAPI + +OpenAPI schema generation now excludes unknown HTTP methods from the generated OpenAPI document. In particular, query methods, which are standard HTTP methods but not recognized by OpenAPI, are now gracefully excluded from the generated OpenAPI document. + +Thank you [@martincostello](https://github.com/martincostello) for this contribution! + +### Improve the description of JSON Patch request bodies + +The OpenAPI schema generation for JSON Patch operations now correctly applies the `application/json-patch+json` media type to request bodies that use JSON Patch. This ensures that the generated OpenAPI document accurately reflects the expected media type for JSON Patch operations. In addition, the JSON Patch request body has a detailed schema that describes the structure of the JSON Patch document, including the operations that can be performed. + +Thank you [@martincostello](https://github.com/martincostello) for this contribution! + +### Use invariant culture for OpenAPI document generation + +OpenAPI document generation now uses invariant culture for formatting numbers and dates in the generated OpenAPI document. This ensures that the generated document is consistent and does not vary based on the server's culture settings. + +Thank you [@martincostello](https://github.com/martincostello) for this contribution! + +## Community contributors + +Thank you contributors! ❤️ + +* [@bkoelman](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3Abkoelman) +* [@campersau](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3Acampersau) +* [@desjoerd](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3Adesjoerd) +* [@Elanis](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3AElanis) +* [@ExtraClock](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3AExtraClock) +* [@h5aaimtron](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3Ah5aaimtron) +* [@kimsey0](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3Akimsey0) +* [@ladeak](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3Aladeak) +* [@martincostello](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3Amartincostello) +* [@medhatiwari](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3Amedhatiwari) +* [@navferty](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3Anavferty) +* [@oroztocil](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3Aoroztocil) +* [@ReaganYuan](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3AReaganYuan) +* [@rkargMsft](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3ArkargMsft) +* [@Sejsel](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3ASejsel) +* [@StickFun](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3AStickFun) +* [@StuartMosquera](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3AStuartMosquera) +* [@WeihanLi](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-rc1+author%3AWeihanLi)