Efcore: Add doc comments to migration files, or disable CS1591

[MaklaCof]

It would be nice if dotnet ef migrations add would automatically add

#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member

to the beginning of generated file and

#pragma warning restore CS1591 // Missing XML comment for publicly visible type or member

at the end of file.
I mean both (migrations and designer).

For example:

#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member

using Microsoft.EntityFrameworkCore.Migrations;
using System;
using System.Collections.Generic;

namespace OpPIS.Web.Hosting.Migrations
{
    public partial class Fix5 : Migration
    {
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.AddColumn<int>(
                name: "ParentAnchorX",
                table: "VarDesign_Parameter-ImageManipulations",
                nullable: true);
        }

        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropColumn(
                name: "ParentAnchorX",
                table: "VarDesign_Parameter-ImageManipulations");
        }
    }
}

#pragma warning restore CS1591 // Missing XML comment for publicly visible type or member

[ajcvickers]

@MaklaCof We will have a think about adding XML comments to the generated code, but we don't plan to do it at the present time. Beyond that, we don't want to generate this pragma all the time because most people will not need it. However, there is a similar discussion about auto-generated in issue #10203. I posted a code snippet in that issue showing how to override the generator to add a line--this should also work for the pragma.

[bobvandevijver]

For reference in this ticket, this is what I used to generate the pragma's:

public class FooMigrationsGenerator : CSharpMigrationsGenerator
{
    private const string PragmaWarningDisable = @"#pragma warning disable 1591";
    private const string PragmaWarningRestore = @"#pragma warning restore 1591";

    public FooMigrationsGenerator(
        MigrationsCodeGeneratorDependencies dependencies, CSharpMigrationsGeneratorDependencies csharpDependencies)
        : base(dependencies, csharpDependencies)
    {
    }

    public override string GenerateMigration(string migrationNamespace, string migrationName,
                                             IReadOnlyList<MigrationOperation> upOperations,
                                             IReadOnlyList<MigrationOperation> downOperations)
    {
        return PragmaWarningDisable
               + Environment.NewLine
               + base.GenerateMigration(migrationNamespace, migrationName, upOperations, downOperations)
               + Environment.NewLine
               + PragmaWarningRestore
               + Environment.NewLine;
    }

    public override string GenerateMetadata(string migrationNamespace, Type contextType, string migrationName,
                                            string migrationId, IModel targetModel)
        => PragmaWarningDisable
           + Environment.NewLine
           + base.GenerateMetadata(migrationNamespace, contextType, migrationName, migrationId, targetModel)
           + Environment.NewLine
           + PragmaWarningRestore
           + Environment.NewLine;
}

Together with this class somewhere in the starting assembly:

public class DesignTimeServices : IDesignTimeServices
{
    /// <inheritdoc />
    public void ConfigureDesignTimeServices(IServiceCollection services)
    {
        // Register custom migration generator which adds a pragma disable for xml-comments
        services.AddSingleton<IMigrationsCodeGenerator, FooMigrationsGenerator>();
    }
}

[MaklaCof]

This doesn't work anymore with version 3.1.1.
Namespace Microsoft.EntityFrameworkCore.Migrations.Design can not be found.

[ErikEJ]

@MaklaCof This? https://docs.microsoft.com/en-us/ef/core/what-is-new/ef-core-3.0/breaking-changes#dip

[MaklaCof]

@ErikEJ Does anything else changed?

Class CSharpEntityTypeGenerator is found in using Microsoft.EntityFrameworkCore.Scaffolding.Internal;

But there are no methods: GenerateMigration, GenerateSnapshot, GenerateMetadata.
Only:

My Packages are:

    <ItemGroup>
        <PackageReference Include="Autofac" Version="4.8.1" />
        <PackageReference Include="Autofac.Extensions.DependencyInjection" Version="4.3.0" />
        <PackageReference Include="MediatR" Version="5.1.0" />
        <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="3.1.1" />
        <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="3.1.1" />
        <PackageReference Include="Microsoft.AspNetCore.SignalR" Version="1.1.0" />
        <PackageReference Include="Microsoft.AspNetCore.SignalR.Protocols.NewtonsoftJson" Version="3.1.1" />
        <PackageReference Include="Microsoft.AspNetCore.SpaServices.Extensions" Version="3.1.1" />
        <PackageReference Include="Microsoft.CodeAnalysis.FxCopAnalyzers" Version="2.9.8">
          <PrivateAssets>all</PrivateAssets>
          <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
        </PackageReference>
        <PackageReference Include="Microsoft.EntityFrameworkCore" Version="3.1.1" />
        <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="3.1.1">
          <PrivateAssets>all</PrivateAssets>
            <!--
            Without this, Migrations.cs file doesn't compile.
            https://docs.microsoft.com/en-us/ef/core/what-is-new/ef-core-3.0/breaking-changes#dip
            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
          -->
        </PackageReference>
        <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="3.1.1">
          <PrivateAssets>all</PrivateAssets>
          <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
        </PackageReference>
        <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="3.1.0" />
        <PackageReference Include="OpenIddict" Version="2.0.1" />
        <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.1" />
        <PackageReference Include="OpenIddict.Mvc" Version="2.0.1" />
        <PackageReference Include="Swashbuckle.AspNetCore" Version="4.0.1" />
        <PackageReference Include="Z.EntityFramework.Extensions.EFCore" Version="3.0.26" />
        <PackageReference Include="Z.EntityFramework.Plus.EFCore" Version="3.0.29" />
    </ItemGroup>

[ErikEJ]

Possibly, since you are using Internal classes

[Ablinne]

I think this should really be implemented. The counter-arguments

• Most people do not need it
• Documentation comments should eventually be added

are imho invalid, because:

• It is just a single line or two that are helpful to everyone who uses xml documentation and visual studio but do not cost anything for everybody else.
• When documentation comments are eventually added, these pragmas can also be easily removed again. This issue was opened over two years ago!

[roji]

Opening to re-discuss in triage.

[ajcvickers]

This does seem reasonable to do. We should consider using inheritdoc.