These were found building dotnet/docs#19736 - Add correct folders for several spec references. - Correct casing of one anchor tag. - Replace absolute links with relative links.
217 lines
7.2 KiB
Markdown
217 lines
7.2 KiB
Markdown
Extending Partial Methods
|
|
=====
|
|
|
|
## Summary
|
|
This proposal aims to remove all restrictions around the signatures of `partial`
|
|
methods in C#. The goal being to expand the set of scenarios in which these
|
|
methods can work with source generators as well as being a more general
|
|
declaration form for C# methods.
|
|
|
|
See also the [original partial methods specification](../../spec/classes.md#partial-methods).
|
|
|
|
## Motivation
|
|
C# has limited support for developers splitting methods into declarations and
|
|
definitions / implementations.
|
|
|
|
```cs
|
|
partial class C
|
|
{
|
|
// The declaration of C.M
|
|
partial void M(string message);
|
|
}
|
|
|
|
partial class C
|
|
{
|
|
// The definition of C.M
|
|
partial void M(string message) => Console.WriteLine(message);
|
|
}
|
|
```
|
|
|
|
One behavior of `partial` methods is that when the definition is absent then
|
|
the language will simply erase any calls to the `partial` method. Essentially
|
|
it behaves like a call to a `[Conditional]` method where the condition was
|
|
evaluated to false.
|
|
|
|
```cs
|
|
partial class D
|
|
{
|
|
partial void M(string message);
|
|
|
|
void Example()
|
|
{
|
|
M(GetIt()); // Call to M and GetIt erased at compile time
|
|
}
|
|
|
|
string GetIt() => "Hello World";
|
|
}
|
|
```
|
|
|
|
The original motivation for this feature was source generation in the form of
|
|
designer generated code. Users were constantly editing the generated code
|
|
because they wanted to hook some aspect of the generated code. Most notably
|
|
parts of the Windows Forms startup process, after components were initialized.
|
|
|
|
Editing the generated code was error prone because any action which caused the
|
|
designer to regenerate the code would cause the user edit to be erased. The
|
|
`partial` method feature eased this tension because it allowed designers to
|
|
emit hooks in the form of `partial` methods.
|
|
|
|
Designers could emit hooks like `partial void OnComponentInit()` and developers
|
|
could define declarations for them or not define them. In either case though
|
|
the generated code would compile and developers who were interested in the
|
|
process could hook in as needed.
|
|
|
|
This does mean that partial methods have several restrictions:
|
|
|
|
1. Must have a `void` return type.
|
|
1. Cannot have `out` parameters.
|
|
1. Cannot have any accessibility (implicitly `private`).
|
|
|
|
These restrictions exist because the language must be able to emit code when
|
|
the call site is erased. Given they can be erased `private` is the only possible
|
|
accessibility because the member can't be exposed in assembly metadata. These
|
|
restrictions also serve to limit the set of scenarios in which `partial` methods
|
|
can be applied.
|
|
|
|
The proposal here is to remove all of the existing restrictions around `partial`
|
|
methods. Essentially let them have `out`, non-void return types or any
|
|
type of accessibility. Such `partial` declarations would then have the added
|
|
requirement that a definition must exist. That means the language does not
|
|
have to consider the impact of erasing the call sites.
|
|
|
|
This would expand the set of generator scenarios that `partial` methods could
|
|
participate in and hence link in nicely with our source generators feature. For
|
|
example a regex could be defined using the following pattern:
|
|
|
|
```cs
|
|
[RegexGenerated("(dog|cat|fish)")]
|
|
partial bool IsPetMatch(string input);
|
|
```
|
|
|
|
This gives both the developer a simple declarative way of opting into generators
|
|
as well as giving generators a very easy set of declarations to look through
|
|
in the source code to drive their generated output.
|
|
|
|
Compare that with the difficulty that a generator would have hooking up the
|
|
following snippet of code.
|
|
|
|
```cs
|
|
var regex = new RegularExpression("(dog|cat|fish)");
|
|
if (regex.IsMatch(someInput))
|
|
{
|
|
|
|
}
|
|
```
|
|
|
|
Given that the compiler doesn't allow generators to modify code hooking up this
|
|
pattern would be pretty much impossible for generators. They would need to
|
|
resort to reflection in the `IsMatch` implementation, or asking users to change
|
|
their call sites to a new method + refactor the regex to pass the string literal
|
|
as an argument. It's pretty messy.
|
|
|
|
## Detailed Design
|
|
The language will change to allow `partial` methods to be annotated with an
|
|
explicit accessibility modifier. This means they can be labeled as `private`,
|
|
`public`, etc ...
|
|
|
|
When a `partial` method has an explicit accessibility modifier
|
|
though the language will require that the declaration has a matching
|
|
definition even when the accessibility is `private`:
|
|
|
|
```cs
|
|
partial class C
|
|
{
|
|
// Okay because no definition is required here
|
|
partial void M1();
|
|
|
|
// Okay because M2 has a definition
|
|
private partial void M2();
|
|
|
|
// Error: partial method M3 must have a definition
|
|
private partial void M3();
|
|
}
|
|
|
|
partial class C
|
|
{
|
|
private partial void M2() { }
|
|
}
|
|
```
|
|
|
|
Further the language will remove all restrictions on what can appear on a
|
|
`partial` method which has an explicit accessibility. Such declarations can
|
|
contain non-void return types, `out` parameters, `extern` modifier,
|
|
etc ... These signatures will have the full expressivity of the C# language.
|
|
|
|
```cs
|
|
partial class D
|
|
{
|
|
// Okay
|
|
internal partial bool TryParse(string s, out int i);
|
|
}
|
|
|
|
partial class D
|
|
{
|
|
internal partial bool TryParse(string s, out int i) { }
|
|
}
|
|
```
|
|
|
|
This explicitly allows for `partial` methods to participate in `overrides` and
|
|
`interface` implementations:
|
|
|
|
```cs
|
|
interface IStudent
|
|
{
|
|
string GetName();
|
|
}
|
|
|
|
partial class C : IStudent
|
|
{
|
|
public virtual partial string GetName();
|
|
}
|
|
|
|
partial class C
|
|
{
|
|
public virtual partial string GetName() => "Jarde";
|
|
}
|
|
```
|
|
|
|
The compiler will change the error it emits when a `partial` method contains
|
|
an illegal element to essentially say:
|
|
|
|
> Cannot use `ref` on a `partial` method that lacks explicit accessibility
|
|
|
|
This will help point developers in the right direction when using this feature.
|
|
|
|
Restrictions:
|
|
- `partial` declarations with explicit accessibility must have a definition
|
|
- `partial` declarations and definition signatures must match on all method
|
|
and parameter modifiers. The only aspects which can differ are parameter names
|
|
and attribute lists (this is not new but rather an existing requirement of
|
|
`partial` methods).
|
|
|
|
## Questions
|
|
|
|
### partial on all members
|
|
Given that we're expanding `partial` to be more friendly to source generators
|
|
should we also expand it to work on all class members? For example should we
|
|
be able to declare `partial` constructors, operators, etc ...
|
|
|
|
**Resolution**
|
|
The idea is sound but at this point in the C# 9 schedule we're trying to avoid
|
|
unnecessary feature creep. Want to solve the immediate problem of expanding
|
|
the feature to work with modern source generators.
|
|
|
|
Extending `partial` to support other members will be considered for the C# 10
|
|
release. Seems likely that we will consider this extension.
|
|
|
|
### Use abstract instead of partial
|
|
The crux of this proposal is essentially ensuring that a declaration has a
|
|
corresponding definition / implementation. Given that should we use `abstract`
|
|
since it's already a language keyword that forces the developer to think about
|
|
having an implementation?
|
|
|
|
**Resolution**
|
|
There was a healthy discussion about this but eventually it was decided against.
|
|
Yes the requirements are familiar but the concepts are significantly different.
|
|
Could easily lead the developer to believe they were creating virtual slots when
|
|
they were not doing so.
|