Proposal: Scoped or Internal Extension Methods (Helper Methods)

[mirmostafa]

Problem Statement

Currently, in C#, there is no standard mechanism for providing reusable, functional, stateless logic (such as pure methods) that can be scoped only to a specific group of types (e.g., repositories with shared CRUD behavior) without exposing those methods to the entire codebase.

While extension methods allow attaching utility logic to types, they are always globally visible wherever the target type and the static class are accessible. This breaks encapsulation and may expose helper algorithms or internal logic to unintended parts of the codebase, increasing the risk of misuse and complicating maintainability.

Developers often rely on public or static utility classes, which don't provide semantic grouping or controlled visibility, making the API surface less predictable and more error-prone.

---

Real-world Scenario

For example, when working with a group of repository classes that must all support a common behavior, such as soft delete, there is currently no way to provide a utility method that is only available to those repositories and hidden from the rest of the codebase.

The typical approach is to create a public or static utility class with methods like SoftDelete, but this exposes implementation details to all developers, even those who shouldn't use it directly. A developer might mistakenly bypass validation logic and directly delete critical data without proper checks, thus breaking encapsulation and increasing risk.

---

Proposed Solution

To improve separation of concerns and centralize reusable logic, we propose introducing a new construct—"helper methods"—that function similarly to extension methods but with controlled visibility.

Unlike extension methods (globally visible), helper methods would only be accessible within the target class, interface, or a specific scope (such as within an assembly). This would encapsulate reusable logic appropriately, reducing misuse.

One possible approach is allowing extension methods to have access modifiers such as private or internal, restricting visibility to the containing type, interface, or assembly.

---

Benefits and Code Example

• Similar to extension methods, enables sharing common logic across multiple types without inheritance.
• If helper algorithms require validation, multi-task coordination, or complex workflows, they won't be visible or misused outside intended classes—even within the same assembly.

Proposed Syntax Example:

private static async Task SafeDelete(this IRepositoryMarker _, string tableName, object id, IDbConnection db, CancellationToken cancellationToken)
    => await db.CreateQuery($"UPDATE {tableName} SET IsDelete = 1, DeleteOn = GETDATE() WHERE Id = @Id")
        .AddParameter("Id", id)
        .ExecuteAsync(cancellationToken);

private static async Task SafeDelete(this IRepositoryMarker _, string tableName, object id, IConnectionFactory factory, CancellationToken cancellationToken)
{
    var db = await factory.CreateWriteConnection(cancellationToken);
    await SafeDelete(_, tableName, id, db, cancellationToken);
}

---

Related Work in Other Languages

Some languages (Kotlin, Swift) support scoped visibility (file-level), and recent versions of C# (since C# 11) support file-scoped types (file modifier). However, no major language currently allows extension methods scoped semantically to specific interfaces or groups of types, suggesting this feature fills a genuine gap.

---

Potential Drawbacks

Introducing scoped visibility helper methods similar to extension methods could increase language complexity. Developers may initially find it challenging to determine when to use extension versus helper methods, potentially leading to confusion.

However, this complexity can be mitigated by careful design, clear documentation, and possibly IDE tooling indicating the visibility and scope of helper methods.

---

Open Question to the Community

Would you find scoped-visibility helper methods useful in your projects, or do you have alternative suggestions for addressing the encapsulation issues discussed above?

[huoyaoyuan]

First of all, designs restricting accessibility of members are usually for custom analyzers instead of the language itself.

One possible approach is allowing extension methods to have access modifiers such as private or internal, restricting visibility to the containing type, interface, or assembly.

It is always supported. You can limit the accessibility by type or individual method.

[mirmostafa]

Thanks for your response!

You're absolutely right that static analyzers and internal/file-scoped constructs can help to some extent—but they don't fully solve the core issue.

Static analyzers only warn after misuse; they don’t prevent it at the language level. And file-scoped or internal methods are often too coarse-grained—they apply to entire files or assemblies, not specific semantic boundaries like a type interface or a bounded group of related components.

What I’m trying to achieve is a language-level mechanism that allows defining extension methods that are logically scoped—for example, only visible to types implementing a specific interface, or within a specific subdomain. This is something that's handled elegantly in languages like Kotlin and Swift.

I'm aiming for stricter encapsulation and reduced surface area for misuse, especially in large codebases or team environments where loose visibility quickly leads to bugs.

I appreciate your thoughts if you’ve seen this solved differently in practice!

[martin-steinhoefer]

@mirmostafa
Do you ask for nested extensions? Extensions declared inside IRepositoryMarker with the possible visibility of protected could achieve the goal you describe - i.e. they would be only visible inside the interface itself and those classes implementing it. If so, then have a look at #9312.
Of course, that proposal does not explicitly talk about declaring extensions within an interface, and there is no notion of protected visibility yet - but that could become part of the proposal.
On the other hand, you are free to place your extensions in a file-scoped static class - so they are accessible only within that file.

[mirmostafa]

Thanks for pointing out issue #9312—that's very relevant and quite close to what I'm proposing!

What I’m envisioning is an ability to define extension methods that are scoped by interface or marker-type, not just by file or assembly. For example, I’d like to write a SoftDelete() extension method that is only available to repositories implementing a marker interface like ISoftDeletableRepository.

The current workaround using file-scoped static classes doesn’t scale well when the logic needs to be shared across multiple types but still constrained within a semantic boundary. And there’s no way today to prevent misuse unless you fall back to verbose patterns like internal utility classes and naming conventions.

Nested extension members with access modifiers like internal or protected inside interface-specific scopes would solve this elegantly. Kotlin and Swift provide this kind of fine-grained control, and I believe C# could benefit greatly from similar capabilities.

Would love your feedback on whether you see any risks in introducing such a visibility model!

[mirmostafa]

Real-world Example: Need for Truly Scoped/Internal Extension Methods in C#

Let's consider a real business case with marker interfaces for soft deletion:

public interface ISoftDeletableModel
{
    bool IsDeleted { get; set; }
    DateTime? DeletedAt { get; set; }
    string? DeletedBy { get; set; }
}

public interface ISoftDeletableRepository<TModel>
    where TModel : ISoftDeletableModel
{ }

Suppose we have multiple repositories (e.g., UserRepository, ProductRepository) that both implement ISoftDeletableRepository<TModel>. We want to add an extension method for soft-deleting models:

public static class Helpers
{
    extension<TModel>(ISoftDeletableRepository<TModel> repository)
        where TModel : ISoftDeletableModel
    {
        // Imagine this extension contains multiple methods with different visibility:
        public void UsefulHelper1(TModel model) { /* ... */ }
        public void UsefulHelper2(TModel model) { /* ... */ }
        
        // The key problem:
        private void SoftDelete(TModel model, string deletedBy)
        {
            if (model == null) throw new ArgumentNullException(nameof(model));
            model.IsDeleted = true;
            model.DeletedAt = DateTime.UtcNow;
            model.DeletedBy = deletedBy;
            // Save changes in repository
        }
    }
}

The Problem

There is currently no way in C# to ensure that ONLY the SoftDelete extension method is visible exclusively INSIDE repositories implementing ISoftDeletableRepository<TModel>, while allowing other extension methods to be more broadly accessible if desired.

• If you make all methods public, they are visible everywhere.
• If you make all methods internal or file-scoped, you can't fine-tune visibility—everything is either too broad or too restricted.
• There is no mechanism in C# to say: "This particular extension method is only accessible from within types implementing this interface, but other helpers can be public or internal as needed."

For example: You might want UsefulHelper1 and UsefulHelper2 to be public/internal, but strictly restrict SoftDelete so that ONLY code inside the actual repository types (e.g., ProductRepository, UserRepository) can use it. Right now, this is impossible.

This means accidental misuse is always possible: as long as someone has a reference to the repository, they can call every extension—regardless of whether it's intended by the domain logic.

What We Need

We need a language feature where access modifiers (such as private or scoped) on extension methods would restrict visibility to only the implementing types themselves, without limiting all methods within the extension scope:

extension<TModel>(ISoftDeletableRepository<TModel> repository)
    where TModel : ISoftDeletableModel
{
    public void UsefulHelper1(TModel model) { /* ... */ }
    public void UsefulHelper2(TModel model) { /* ... */ }
    
    private void SoftDelete(TModel model, string deletedBy)
    {
        // Only visible INSIDE the implementing repository types
    }
}

This is a real, unsolved problem for proper encapsulation and domain safety in modern C#.

[martin-steinhoefer]

@mirmostafa
I understand your desire and would love to see nested extensions coming. But:

Can you explain, why visibility of SoftDelete must be restricted such, that only implementors of ISoftDeletableRepository<T> can access it? Where is the concrete problem, being it public or internal? Why placing the extension into a separate namespace is not sufficient?

You could perhaps make SoftDelete a default interface member of ISoftDeletableReposotory<T>. That allows for protected implementation, which is visible only to implementors of the interface. If not, you perhaps could explain, why that is no viable way to solve the problem, and why extensions are required.

[mirmostafa]

Apologies for my delayed reply—life in Iran (especially with the disastrous state of internet connectivity lately) has made it extremely difficult to keep up with technical discussions, even on crucial topics.
Thank you all for your patience and thoughtful feedback!

Your question about the semantics of private extension methods is absolutely valid, and I appreciate you highlighting the ambiguity.
The core idea is to enable finer-grained encapsulation for helper/utility methods that should only be accessible inside the implementing type itself, not via any external call—even if that external caller has a reference to the target interface.

Currently, C# allows us to encapsulate logic in instance methods (fully private/protected), but any logic extracted into an extension method becomes globally accessible as long as the type/interface is in scope.
The proposal is not to make extension methods “private” to their module or assembly, but to restrict their usability only inside the type(s) that implement a certain interface or pattern—essentially, making the helper a true internal member from the perspective of the implementing type, even if it lives outside it.

This model could be analogous to private static helper methods within a type, but with the reusability and composition power of extension methods.
The implementation challenge is clear—but so is the maintainability/safety gap for real-world, large-scale codebases.

I'd love to hear more about any precedent or alternative approaches you've seen in other languages or large systems!

[martin-steinhoefer]

@mirmostafa
It seems, I don't quite get the point: you want extensions, that are declared publicly but apply only within a subtype of certain types like an interface?
To me extensions work the following way:
They are declared in a top-level static class (either public or internal) so the methods become accessible either publicly or just in the very same assembly (and it's 'friends').
Extensions declare a 'receiver' that is the type that will be 'extended'. Extensions then can be syntactically invoked like any ordinary member of the extended type. That restricts applicability to the receiver type (and it's descendants - if any).

Currently there is no way to restrict neither accessibility nor applicability. There is a proposal (#9312) that deals with the restriction of accessibility by the means of declaring extensions nested - i.e. inside a normal class or interface - to be accessible from within that nesting type (and perhaps it's descendants).

There is no proposal that I know of, that deals with restricting applicability - i.e. restraining the places where the extension can be invoked syntactically. And you propose exactly that? Do I correctly understand you? You want a mechanism, that restricts the places where an otherwise accessible extension can be applied only at the interior of certain types - which are somehow are defined (interface or something completely different). Can you explain, how the application of extensions should be restricted?

Are you aware, that applicability of an extension actually is governed by the accessibility of the extension and the receiver type (and the parameters too). Having an extension being declared nested within a type (as per #9312) would perfectly solve your problem - I think.

Where did I miss something?

Regarding a special case: nested extensions on the nesting type i.e. something like this

public class Defined
{
    protected static class DefinedExtensions
    {
         public static void DoSomething(this Defined d, ...) => ... ;
    }
}

is semantically equivalent to

public class Defined
{
    protected void DoSomething(...) => ... ;
}

without any additional feature and less complexity.

So from your problem domain only use cases for extensions on types other than the nesting one remain. And for those the question arises - why should the extension be restricted to the inner of the type (or it's descendants)? What actual problem will be solved by that? What prohibits public or internal visibility of the extensions?

[mirmostafa]

Thank you for your thoughtful response and for referencing proposal #9312—it's closely related to the direction I have in mind.

Let me clarify my core concern: it's not just about restricting extension visibility to a receiver or an assembly, but about semantic scoping of extension helpers to specific usage boundaries—such as within the interior logic of a type implementing a particular interface, not simply to its type signature.

The key problem with the current model is that as soon as an extension helper is public or internal, any code with access to the target type (even outside its intended domain or context) can invoke it. In complex codebases with critical business rules, this can allow accidental bypassing of invariants or essential logic paths.

Nesting extension classes helps with accessibility, but doesn't allow for applicability to be further scoped—for instance, ensuring a SoftDelete() extension on ISoftDeletableRepository is only available within actual repository logic, and never outside it, regardless of imports or visibility.

This is a pain point that emerges in very large and modular codebases, where utility extensions are easily misused across layers or modules.

My goal is to spark a discussion about whether C# could eventually provide a fine-grained visibility mechanism for extension helpers, so that reusable helpers could be tightly scoped both by receiver and by contextual usage.

Would love your perspective—do you think this need is addressed by #9312 or does it require something even more granular?

[CyrusNajmabadi]

so that ONLY code inside the actual repository types (e.g., ProductRepository, UserRepository) can use it. Right now, this is impossible.

I can't think of a use case where I want this.

This means accidental misuse is always possible

Why would this be accidental misuse?

[HaloFour]

If the goal is to define a subset of the existing language, up to and including enforcement of accessibility not provided, then yes, analyzers would be the appropriate way to implement that. Their biggest benefit is that they can be implemented now, with a relatively little effort in your part, vs. waiting for the language team. That would likely take several years at a minimum, even assuming they consider it something worthwhile to do. However, I honestly don't think the language team would consider this as extensions have been intentionally designed to be public and accessible, scoped only by the presence of the extension class, which must be public.

[huoyaoyuan]

• Analyzers can only warn or block after code is written—they cannot enforce restrictions at the language/compiler level. This means accidental or intentional misuse may still slip through, especially if analyzers are disabled or ignored.

No. Analyzers are deeply integrated with the compiler. The errors reported by analyzers are honored by compiler and will block compilation.

• In large teams or codebases, relying only on analyzers means consistency depends on correct configuration and usage everywhere.

It is very easy to enforce analyzers in large codebase. Microsoft enforces various analyzers in its internal huge codebases by one centralized configuration file per repo. Analyzers are specifically designed for such customization.

• A language-level visibility or applicability feature would express the developer's intent directly and provide compile-time enforcement, which is both safer and clearer.

Analyzers are compile-time. There are multiple languages and compiler versions. Enforcing a language version is not much different from enforcing an analyzer.

Language feature is always enabled for everyone, while analyzers can be selectively enabled. Language feature must show its value for every user, not a particular pattern.

[mirmostafa]

Thank you all for your detailed and thoughtful responses.

I fully understand the power and flexibility of analyzers, especially in large organizations with centralized configuration. My experience, however, is that even in well-governed codebases, analyzer enforcement is not always foolproof—sometimes intentionally (for expedience or legacy reasons), sometimes by accident.

A language-level feature provides an always-on, intent-revealing safeguard, which analyzers—while valuable—can't guarantee in every real-world scenario.

One additional benefit of a language-level visibility feature is its direct impact on developer experience at coding-time: when scoped extension methods are defined, IDEs and tooling like IntelliSense would only suggest these methods within the allowed context (e.g., inside the relevant class or interface).

This means developers are guided away from misusing helpers—not just at build-time, but even during code writing—since these helpers would not appear in auto-complete or as available members outside the proper scope.

Analyzers, in contrast, can only warn after the fact. With language-level support, accidental misuse becomes nearly impossible even at the point of code entry, which is a significant boost for productivity and correctness—especially in large teams or codebases.

That said, I appreciate the reality of language design priorities and the need for features to serve the broadest community. Even if this isn't the right time for such a feature, I hope documenting this pain point is helpful for future reference. Thank you for engaging in the discussion and for all the insights shared.

If this scenario becomes more prevalent in the future, I hope the language team will reconsider!

[HaloFour]

Yes, language features can have better developer support, especially as language designers and IDE developers are responsible for implementing them. That's also what makes them prohibitively expensive and massively time consuming to implement.

The pattern you are requesting is an unusual one, and one extension members were not designed to address. You also seem to be the only person who has asked for such accessibility features for extension methods, despite the fact that the language feature is 18 years old and enjoys very widespread usage throughout the ecosystem. That would make it seem that the beneficiary of such a language feature would be incredibly small. As such, it would be very unlikely that the team would consider such a change. Maybe it could be considered as a part of a larger story around extension accessibility in general, but even that seems very unlikely.

Analyzers were added to the C# compiler very explicitly to satisfy these kinds of requests. They remove the language and IDE teams from being bottlenecks to you solving your problem for your teams and codebase. You could even publish them to NuGet to benefit the wider ecosystem. If the community furnished an analyzer for this purpose and it found widespread usage, that would be the indicator to the language team that it might be worth becoming a first class feature in the language in the future.

[mirmostafa]

Thank you again for all the thoughtful feedback and perspectives shared here.
My main goal was to document this pain point and better understand the trade-offs.
Even if this isn’t the right time for such a feature, I really appreciate the discussion and the clarifications provided.
Hopefully, if this scenario becomes more relevant in the future, the language team and community can revisit it.
Thanks again for the time and valuable insights! 🙏