是否使用了“异步"功能?方法名称的后缀取决于是否使用了'async'修饰符? [英] Does the use of the "Async" suffix in a method name depend on whether the 'async' modifier is used?

问题描述

在方法名称后缀"Async"的约定是什么?

是否应将异步"后缀仅附加到使用async修饰符声明的方法中?

public async Task<bool> ConnectAsync()

还是该方法仅返回Task<T>或Task就足够了吗?

public Task<bool> ConnectAsync()

解决方案

即使从Microsoft文档中，我也认为事实是模棱两可的:

在Visual Studio 2012和.NET Framework 4.5中， 带有async关键字(在Visual Basic中为Async)的属性是 被认为是异步方法，而C#和Visual Basic 编译器执行必要的转换以实现 通过使用TAP异步方法.异步方法应 返回Task或Task<TResult>对象.

http://msdn.microsoft.com/en-us /library/hh873177(v=vs.110).aspx

那还不对.任何具有async的方法都是异步的，然后说应该返回Task或Task<T>-这不适用于调用堆栈顶部的方法，例如Button_Click或async void. /p>

当然，您必须考虑公约的意义是什么?

您可以说Async后缀约定是为了向API用户传达该方法是可以等待的.对于等待使用的方法，必须为空白返回Task，对于值返回方法必须返回Task<T>，这意味着只有后者可以带有Async后缀.

或者您可能会说Async后缀约定是为了传达该方法可以立即返回的信息，从而放弃当前线程来执行其他工作并可能导致争用.

此Microsoft Doc引用说:

按照惯例，将异步"附加到具有 异步或异步修饰符.

http://msdn.microsoft.com/en-us/library/hh191443.aspx #BKMK_NamingConvention

什至没有提到您自己的返回Task的异步方法需要Async后缀，我认为我们都同意这样做.

---

因此，这个问题的答案可能是:两者都有.在这两种情况下，都需要将Async附加到带有async关键字的方法上，并返回Task或Task<T>.

---

我要请斯蒂芬·图布(Stephen Toub)澄清情况.

更新

所以我做到了.这就是我们的好男人写的:

如果公共方法是Task-returning并且本质上是异步的(如 与已知总是同步执行的方法相反 完成但由于某种原因仍返回任务)，它应该具有 一个异步"后缀.那就是指导方针.这里的主要目标 命名是为了使它对消费者非常明显 被调用的方法可能无法完成的功能 其所有工作同步进行；当然也可以帮助解决这个问题 同步和异步都公开了功能 这样，您就需要一个名称差异来区分它们.如何 该方法实现其异步实现对 命名:是否使用async/await来获得编译器的帮助， 或者是否使用System.Threading.Tasks中的类型和方法 直接(例如TaskCompletionSource)并不重要，因为 不会影响该方法的签名，甚至不会影响该方法的使用者 有关方法.

当然，对于 准则.在命名方面，最值得注意的是案例 整个类型的存在理由是要提供以异步为重点的 功能，在这种情况下，每个方法上都具有Async 过度杀伤Task本身产生其他Task的方法.

对于返回空值的异步方法，不希望具有 那些在公共区域内的人，因为呼叫者没有好的方法 知道异步工作何时完成.如果必须暴露 一个公开的返回空值的异步方法，但是，您可能会这样做 想要有一个传达异步工作的名字 启动后，您可以在此处使用异步"后缀. 考虑到这种情况应该很少见，我认为这确实是一个 视具体情况而定.

我希望能有所帮助，史蒂夫

斯蒂芬开场白的简洁指导很清楚.它不包含async void，因为通常不希望使用这种设计来创建公共API，因为实现异步void的正确方法是返回一个普通的Task实例，并使编译器发挥其魔力.但是，如果您确实需要public async void，则建议附加Async.其他栈顶async void方法(例如事件处理程序)通常是不公开的，无关紧要/不合格.

对我来说，它告诉我，如果我发现自己想在async void上加Async后缀，我可能应该将其转换为async Task，以便呼叫者可以等待它，然后附加Async. /p>

What is the convention for suffixing method names with "Async"?

Should the "Async" suffix be appended only to a method that is declared with the async modifier?

public async Task<bool> ConnectAsync()

Or is it enough that the method just returns Task<T> or Task?

public Task<bool> ConnectAsync()

解决方案

I think the truth is ambiguous even from Microsoft documentation:

In Visual Studio 2012 and the .NET Framework 4.5, any method that is attributed with the async keyword (Async in Visual Basic) is considered an asynchronous method, and the C# and Visual Basic compilers perform the necessary transformations to implement the method asynchronously by using TAP. An asynchronous method should return either a Task or a Task<TResult> object.

http://msdn.microsoft.com/en-us/library/hh873177(v=vs.110).aspx

That's not right already. Any method with async is asynchronous and then its saying it should return either a Task or Task<T> - which isn't right for methods at the top of a call stack, Button_Click for example, or async void.

Of course, you have to consider what is the point of the convention?

You could say that the Async suffix convention is to communicate to the API user that the method is awaitable. For a method to be awaitable, it must return Task for a void, or Task<T> for a value-returning method, which means only the latter can be suffixed with Async.

Or you might say that the Async suffix convention is to communicate that the method can return immediately, relinquishing the current thread to perform other work and potentially causing races.

This Microsoft doc quote says:

By convention, you append "Async" to the names of methods that have an Async or async modifier.

http://msdn.microsoft.com/en-us/library/hh191443.aspx#BKMK_NamingConvention

Which doesn't even mention that your own asynchronous methods returning Task need the Async suffix, which I think we all agree they do.

---

So the answer to this question could be: both. In both cases, you need to append Async to methods with async keyword and that return Task or Task<T>.

---

I'm going to ask Stephen Toub to clarify the situation.

Update

So I did. And here's what our good man wrote:

If a public method is Task-returning and is asynchronous in nature (as opposed to a method that is known to always execute synchronously to completion but still returns a Task for some reason), it should have an "Async" suffix. That’s the guideline. The primary goal here with the naming is to make it very obvious to a consumer of the functionality that the method being invoked will likely not complete all of its work synchronously; it of course also helps with the case where functionality is exposed with both synchronous and asynchronous methods such that you need a name difference to distinguish them. How the method achieves its asynchronous implementation is immaterial to the naming: whether async/await is used to garner the compiler’s help, or whether types and methods from System.Threading.Tasks are used directly (e.g. TaskCompletionSource) doesn’t really matter, as that doesn’t affect the method’s signature as far as a consumer of the method is concerned.

Of course, there are always exceptions to a guideline. The most notable one in the case of naming would be cases where an entire type’s raison d’etre is to provide async-focused functionality, in which case having Async on every method would be overkill, e.g. the methods on Task itself that produce other Tasks.

As for void-returning asynchronous methods, it’s not desirable to have those in public surface area, since the caller has no good way of knowing when the asynchronous work has completed. If you must expose a void-returning asynchronous method publicly, though, you likely do want to have a name that conveys that asynchronous work is being initiated, and you could use the "Async" suffix here if it made sense. Given how rare this case should be, I’d argue it’s really a case-by-case kind of decision.

I hope that helps, Steve

The succinct guidance from Stephen’s opening sentence is clear enough. It excludes async void because it is unusual to want to create a public API with such a design since the correct way to implement an asynchronous void is to return a plain Task instance and let the compiler to its magic. However, if you did want a public async void, then appending Async is advised. Other top-of-stack async void methods such as event handlers are usually not public and don’t matter/qualify.

For me, it tells me that if I find myself wondering about suffixing Async on an async void, I probably should turn it into an async Task so that callers can await it, then append Async.

这篇关于是否使用了“异步"功能?方法名称的后缀取决于是否使用了'async'修饰符?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！