Umbrella Dotnet Migrate Repo Controller To Data Service

---
name: umbrella-dotnet-migrate-repo-controller-to-data-service
description: 'Migrate an existing GenericRepositoryApiController (Pattern 1, direct repository) to GenericRepositoryDataServiceApiController (Pattern 2, backing controller service). Creates the controller service, updates the controller, and rewires DI. Run umbrella-dotnet-rename-client-repository-to-service first if the client interface still uses the ...Repository naming convention.'
---

# Migrate Repo Controller to Data Service Controller

## Purpose

Upgrade an existing Pattern 1 API controller (inheriting `GenericRepositoryApiController`, direct repository access) to Pattern 2 (inheriting `GenericRepositoryDataServiceApiController`, backed by a controller service). This enables Blazor SSR pre-rendering support and moves all CRUD hooks into a dedicated controller service class.

**Prerequisites:**
- The API controller to migrate must already exist.
- If the client data interface still uses the `...Repository` naming convention, run `umbrella-dotnet-rename-client-repository-to-service` first to rename it to `...Service` and move it to `Services\Abstractions\`.
- If no client interface exists yet (API-only project), one will be created as part of this skill.

## Discovery (read these before writing anything)

1. Read the existing controller at `Web\<AppName>.Web.Server\Controllers\Api\Manage<Name>Controller.cs` in full — capture the current base class, all generic type params, all constructor dependencies, and any lifecycle hook overrides (`AfterCreateEntityAsync`, `AfterUpdateEntityAsync`, `AfterDeleteEntityAsync`).
2. Read 1–2 existing controller services in `Web\<AppName>.Web.Server\Services\` (fall back to the legacy `Web\<AppName>.Web.Server\Services\Api\` location in older projects) to confirm the `UmbrellaRepositoryDataService` generic parameter order and project-specific patterns.
3. **Determine if a client service interface already exists:** Check `Web\<AppName>.Web.Client.Data\Services\Abstractions\I<Name>Service.cs`. If it exists (after running the rename skill), the server registration must use `ReplaceScoped`. If it does not exist, create it and use `AddScoped`.
4. Read `Web\<AppName>.Web.Server\IServiceCollectionExtensions.cs` — `// Controller Services` section — to confirm the current DI state for this feature.

---

## Step 1 -- Ensure the service interface exists

**If already created by `umbrella-dotnet-rename-client-repository-to-service`:** skip this step.

**If creating fresh** (no client data project, or the interface was never created):

**File:** `Web\<AppName>.Web.Client.Data\Services\Abstractions\I<Name>Service.cs` (Blazor project)  
or `Web\<AppName>.Web.Server\Services\Abstractions\I<Name>Service.cs` (API-only project)

```csharp
using <AppName>.Web.Shared.Models.Api.<Feature>;
using Umbrella.Utilities.Data.Pagination;

namespace <AppName>.Web.[Client.Data|Server].Services.Abstractions;

public interface I<Name>Service : IGenericDataService<
    <Name>Model,
    int,
    Slim<Name>Model,
    PaginatedResultModel<Slim<Name>Model>,
    Create<Name>Model,
    Create<Name>ResultModel,
    Update<Name>Model,
    Update<Name>ResultModel>;
```

Use the existing controller's concrete model types. Pattern 2's generic controller and `IGenericDataService` contract require real keyed/read/update types and cannot use Pattern 1's `object`/`NoOp*` placeholders. If the old controller disabled an operation with placeholders, locate or scaffold the corresponding concrete models first, then preserve the disabled endpoint behavior through the controller service's `XxxEndpointEnabled => false` override. Stop for the model prerequisite when no correct concrete type exists.

---

## Step 2 -- Create the controller service

**File:** `Web\<AppName>.Web.Server\Services\<Name>ControllerService.cs`

Concrete controller services live directly in the `Services` folder, alongside the `Services\Abstractions\` interfaces folder — even when the project has existing controller services in the legacy `Services\Api\` location.

Extract lifecycle hook logic and all endpoint-enablement and authorization-check overrides from the existing controller into this new class. If the controller had no hooks, the service body may contain only those behavioral overrides.

```csharp
using <AppName>.Core.Data.Repositories.Abstractions;
using <AppName>.Core.Domain.Entities;
using <AppName>.Web.[Client.Data|Server].Services.Abstractions;
using <AppName>.Web.Shared.Models.Api.<Feature>;
using Umbrella.DataAccess.Abstractions;
using Umbrella.DataAccess.Abstractions.Options;
using Umbrella.Utilities.Data.Abstractions;
using Umbrella.Utilities.Data.Pagination;
using Umbrella.Utilities.Mapping.Abstractions;
using Umbrella.Utilities.Security.Abstractions;
using Umbrella.Utilities.Threading.Abstractions;

namespace <AppName>.Web.Server.Services;

public class <Name>ControllerService : UmbrellaRepositoryDataService<
    <Name>Model,
    Slim<Name>Model,
    PaginatedResultModel<Slim<Name>Model>,
    Create<Name>Model,
    Create<Name>ResultModel,
    Update<Name>Model,
    Update<Name>ResultModel,
    I<Name>Repository,
    <Name>,
    RepoOptions,
    int>, I<Name>Service
{
    public <Name>ControllerService(
        ILogger<<Name>ControllerService> logger,
        IHostEnvironment hostingEnvironment,
        UmbrellaRepositoryDataServiceOptions options,
        IUmbrellaMapper mapper,
        IUmbrellaAuthorizationService authorizationService,
        ISynchronizationManager synchronizationManager,
        Lazy<IDataAccessUnitOfWork> dataAccessUnitOfWork,
        Lazy<I<Name>Repository> repository,
        IDataExpressionFactory dataExpressionFactory)
        : base(logger, hostingEnvironment, options, mapper, authorizationService,
               synchronizationManager, dataAccessUnitOfWork, repository, dataExpressionFactory)
    {
    }

    protected override bool AuthorizationSlimReadChecksEnabled => false;
    protected override bool AuthorizationCreateChecksEnabled => false;
    protected override bool AuthorizationReadChecksEnabled => false;
    protected override bool AuthorizationUpdateChecksEnabled => false;
    protected override bool AuthorizationDeleteChecksEnabled => false;
}
```

**Migrating controller behavior from the old controller:**

If the original controller had overrides such as:

```csharp
// Old controller (Pattern 1):
protected override async Task AfterCreateEntityAsync(<Name> entity, Create<Name>Model model, Create<Name>ResultModel result, CancellationToken cancellationToken)
{
    cancellationToken.ThrowIfCancellationRequested();
    Guard.IsNotNull(entity);
    Guard.IsNotNull(model);
    Guard.IsNotNull(result);

    _ = await _fileHandler.CreateByGroupIdAndTempFileNameAsync(...);
    UmbrellaVersionedUrl image = await _fileHandler.GetVersionedWebFilePathAsync(...)
        ?? throw new InvalidOperationException("The saved image could not be resolved.");
    result.ImageUrl = image.Url;
    result.ImageVersionToken = image.VersionToken;
}
```

Move lifecycle hooks verbatim into the controller service. Also move every `AuthorizationXxxChecksEnabled` and `XxxEndpointEnabled` override so authorization and disabled endpoints do not change during the migration. Preserve Dynamic Image URL/version-token pairing and asynchronous file lookups. Any extra dependencies (e.g. `I<Name>FileHandler`) that those hooks needed move to the controller service constructor (after the 9 base params):

```csharp
private readonly I<Name>FileHandler _fileHandler;

public <Name>ControllerService(
    // ... 9 base params ...
    I<Name>FileHandler fileHandler)
    : base(...)
{
    _fileHandler = fileHandler;
}
```

**Rules:**
- `public class` (not `internal`).
- `IHostEnvironment` in the constructor (not `IWebHostEnvironment`).
- `UmbrellaRepositoryDataService` generic params (11 total): `TModel` first, then `TSlimModel` — opposite of the controller's order.
- Do not use `object` or `NoOp*` — controller services always use full concrete model types. If the original controller used `object`/NoOp for some positions, use the real model types here (the service supports all operations regardless of which endpoints the controller exposes).

---

## Step 3 -- Rewrite the controller

Replace the existing controller content entirely. The new controller is thin — no overrides, no extra dependencies:

```csharp
using Microsoft.AspNetCore.Authorization;
using <AppName>.Web.[Client.Data|Server].Services.Abstractions;
using <AppName>.Web.Server.Infrastructure.Mvc;
using <AppName>.Web.Shared.Models.Api.<Feature>;
using <AppName>.Web.Shared.Security.Policies;
using Umbrella.Utilities.Data.Pagination;

namespace <AppName>.Web.Server.Controllers.Api;

[Authorize(<AppName>PolicyNames.<Policy>)]
public class <Name>Controller : <AppName>GenericRepositoryDataServiceApiController<
    Slim<Name>Model,
    PaginatedResultModel<Slim<Name>Model>,
    <Name>Model,
    Create<Name>Model,
    Create<Name>ResultModel,
    Update<Name>Model,
    Update<Name>ResultModel,
    int,
    I<Name>Service>
{
    public <Name>Controller(
        ILogger<<Name>Controller> logger,
        IWebHostEnvironment hostingEnvironment,
        Lazy<I<Name>Service> repositoryDataService)
        : base(logger, hostingEnvironment, repositoryDataService)
    {
    }
}
```

**Important:** The model types in the controller (positions T1–T7) must be the same full concrete types declared by the client interface and implemented by the controller service. If the original Pattern 1 controller used `object` or `NoOp*` to disable endpoints, replace those placeholders with the prerequisite concrete types and preserve the old availability through the matching `XxxEndpointEnabled => false` service override.

---

## Step 4 -- Update DI

**File:** `Web\<AppName>.Web.Server\IServiceCollectionExtensions.cs` — `// Controller Services` section, alphabetical order.

**If the client service interface already exists** (created by `umbrella-dotnet-rename-client-repository-to-service` or previously scaffolded by `umbrella-dotnet-scaffold-client-data`):
```csharp
_ = services.ReplaceScoped<I<Name>Service, <Name>ControllerService>();
```

**If no client interface existed before this skill created it:**
```csharp
_ = services.AddScoped<I<Name>Service, <Name>ControllerService>();
```

If the old server DI had any explicit registration for this controller's old repository interface, remove it.

---

## Analyzer compatibility

Before finishing, read `.ai-shared\bundles\umbrella\analyzer-compatibility.md` and build the affected projects with their installed analyzers enabled. Treat diagnostics introduced by the generated or changed code as defects in this workflow.

## Verification

1. The old `Manage<Name>Controller` no longer inherits `GenericRepositoryApiController` — it inherits `<AppName>GenericRepositoryDataServiceApiController` with 9 type params.
2. No lifecycle hooks, endpoint-enablement overrides, or authorization-check overrides remain on the controller — they live in `<Name>ControllerService`.
3. `<Name>ControllerService` is `public class`, lives in `Web\<AppName>.Web.Server\Services\`, inherits `UmbrellaRepositoryDataService` with 11 type params, uses `IHostEnvironment` (not `IWebHostEnvironment`).
4. Any extra dependencies (file handlers, services) from the old controller are now in the controller service constructor, after the 9 base params.
5. Server DI uses `ReplaceScoped` if a client service interface exists, `AddScoped` otherwise.
6. The old controller's `IUmbrellaMapper`, `Lazy<I<Name>Repository>`, and `IUmbrellaRepositoryCoreDataService` constructor dependencies are gone from the controller.