```json
//[doc-seo]
{
    "Description": "Upgrade your ABP solutions from v10.0 to v10.1 with this comprehensive migration guide, ensuring compatibility and new features with ABP v10.1."
}
```

# ABP Version 10.1 Migration Guide

This document is a guide for upgrading ABP v10.0 solutions to ABP v10.1. There are some changes in this version that may affect your applications. Please read them carefully and apply the necessary changes to your application. You may also need to update or check package versions; for internal NuGet package changes, see [package-version-changes.md](../../package-version-changes.md) for reference.

## Open-Source (Framework)

### Swashbuckle.AspNetCore Upgraded to v10

In this version, the `Swashbuckle.AspNetCore` package has been upgraded to v10. This upgrade also updates the underlying `Microsoft.OpenApi` package to v2.x, which introduces breaking changes that may affect your application if you have any custom Swagger/OpenAPI configuration such as custom filters, schema customizations, or security requirements.

**Required Actions:**

- Update any `using` directives that reference types from the `Microsoft.OpenApi.Models` namespace to also include the new `Microsoft.OpenApi` namespace (interfaces such as `IOpenApiSchema` are now in `Microsoft.OpenApi`, while concrete types such as `OpenApiSchema` remain in `Microsoft.OpenApi.Models`).
- Update filter/handler method signatures to accept the new interfaces (e.g. `IOpenApiSchema` instead of `OpenApiSchema`). When you need to mutate properties, cast to the concrete type first. For example:

  ```csharp
  public void Apply(IOpenApiSchema schema, SchemaFilterContext context)
  {
      if (schema is OpenApiSchema openApiSchema)
      {
          // Properties are only mutable on the concrete type
          openApiSchema.Type = JsonSchemaType.String;
      }
  }
  ```
- Replace usage of the `OpenApiSchema.Type` property using a string (e.g. `"string"` or `"boolean"`) with the `JsonSchemaType` flags enumeration.
- Replace usage of the `OpenApiSchema.Nullable` property by OR-ing the `JsonSchemaType.Null` value to `OpenApiSchema.Type` (e.g. `schema.Type |= JsonSchemaType.Null;`).
- Update any use of `.Reference` properties (e.g. `OpenApiSchema.ReferenceV3`) to use the new `*Reference` class instead (e.g. `OpenApiSchemaReference`).
- Update any use of `AddSecurityRequirement()` to use a `Func<OpenApiDocument, OpenApiSecurityRequirement>`.

For a full list of migration steps, please refer to the [Swashbuckle.AspNetCore v10 migration guide](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/docs/migrating-to-v10.md#migration-overview).

> See [#24255](https://github.com/abpframework/abp/pull/24255) for more details.

### Add New EF Core Migrations for Password History/User Passkey Entities

In this version, we added password history/ user passkeys support to the [Identity PRO Module](../../modules/identity-pro.md) to enhance security compliance. A new `IdentityUserPasswordHistory` entity has been added to store previous password hashes, preventing users from reusing recent passwords. Additionally, we have introduced an `IdentityUserPasskey `entity to support passkey-based authentication.

**You need to create a new EF Core migration and apply it to your database** after upgrading to ABP 10.1.

> See [#23894](https://github.com/abpframework/abp/pull/23894) for more details.

### Angular Version Upgraded to v21

ABP now targets Angular v21 (up from v20). For existing Angular projects, apply these changes:

- **TypeScript:** Update to `~5.9.0`
- **main.ts:** Add `provideZoneChangeDetection()` to the bootstrap config:
  ```ts
    // angular/src/main.ts
    bootstrapApplication(AppComponent, {
        ...appConfig,
        providers: [provideZoneChangeDetection(), ...appConfig.providers],
    }).catch(err => console.error(err));
  ```
- **tsconfig.json:** Align with the new property formats to avoid build issues:
  ```json
    /* angular/tsconfig.json */
    /* To learn more about this file see: https://angular.io/config/tsconfig. */
    {
      "compileOnSave": false,
      "compilerOptions": {
        "baseUrl": "./",
        "outDir": "./dist/out-tsc",
        "sourceMap": true,
        "declaration": false,
        "esModuleInterop": true,
        "experimentalDecorators": true,
        "moduleResolution": "bundler",
        "importHelpers": true,
        "skipLibCheck": true,
        "target": "ES2022",
        "module": "ES2022",
        "lib": ["ES2022", "dom", "esnext.disposable"],
        "paths": {},
        "useDefineForClassFields": false
      },
      "angularCompilerOptions": {
        "enableI18nLegacyMessageIdFormat": false
      }
    }
  ```

You may need to update your Node.js version as well. For more details, see the [Angular version reference](https://angular.dev/reference/versions#actively-supported-versions).

## PRO

> Please check the **Open-Source (Framework)** section before reading this section. The listed topics might affect your application and you might need to take care of them.

If you are a paid-license owner and using the ABP's paid version, then please follow the following sections to get informed about the breaking changes and apply the necessary ones:

### AI Management Module: `Workspace` Entity Base Class Changed

In this version, the `Workspace` entity in the [AI Management Module](../../modules/ai-management/index.md) has been changed from `FullAuditedAggregateRoot` to `AuditedAggregateRoot` as the base class. 

**This change removes support for soft deletion and related auditing features. If you are using the AI Management module, you need to create a new EF Core migration and apply it to your database.**

> **Important:** If you have soft-deleted Workspaces in your database, they will become visible after this update. You may need to create a migration script to clean up already deleted records before applying the migration.

### CMS Kit Pro Module: Dynamic FAQ Group Management

In this version, the FAQ group system in the [CMS Kit Pro Module](../../modules/cms-kit-pro/faq.md) has been redesigned to support dynamic group management. FAQ groups are now **first-class entities** stored in the database, replacing the previous static configuration approach.

**Key Changes:**

- A new `FaqGroup` entity has been introduced with unique names for FAQ groups
- The `FaqSection` entity now uses `GroupId` (Guid) instead of `GroupName` (string) _(GroupName is deprecated and will be removed soon. Use GroupId instead.)_
- Static FAQ group configuration (`FaqOptions.SetGroups`) has been removed

**Migration Steps:**

1. **Remove static group configuration** from your code (e.g., `Configure<FaqOptions>(options => { options.SetGroups([...]); })`)
2. **Create a new EF Core migration and apply it to your database**
3. **Run the one-time data migration seeder** to migrate existing FAQ sections to the new group entity model

> **Note:** If you have existing FAQ data, you may need to create a data seeder to migrate your existing group associations to the new entity-based model.