تطبيق حدث-إلى نقش غير متزامن

If you are writing a فئة مع some العمليات that may incur noticeable delays, consider giving it غير متزامن functionality بواسطة implementing نظرة عامة تستند إلى حدث غير متزامن نقش حول.

غير متزامن تستند إلى حدث نقش يوفر طريقة قياسية لحزم فئة الذي يحتوي على ميزات غير متزامنة. If implemented مع helper فئات مثل AsyncOperationManager, your فئة will work correctly under أي نمط تطبيق, including ASP.NET, Console applications, و Windows Forms applications.

For an مثال that implements the حدث-based نمط غير متزامن, see كيفية القيام بما يلي: تنفيذ مكوّن التي تعتمد على النقش غير متزامن يستند إلى حدث.

For simple غير متزامن العمليات, you may بحث the BackgroundWorker مكوّن suitable. لمزيد من المعلومات حول BackgroundWorker، راجع كيفية القيام بما يلي: تشغيل عملية في الخلفية.

وتصف القائمة التالية ميزات غير متزامن تستند إلى حدث نقش التي تمت مناقشتها في هذا الموضوع.

• فرص لتطبيق حدث-إلى نقش غير متزامن

• تسمية وظائف غير متزامن

• بشكل اختياري دعم الإلغاء

• بشكل اختياري دعم خاصية IsBusy

• بشكل اختياري توفير دعم لتقرير عن التقدم

• بشكل اختياري توفير دعم لإرجاع نتائج تزايدي

• Hوling مخرج و المرجع معلمات في وظائف

فرص لتطبيق حدث-إلى نقش غير متزامن

خذ بعين الاعتبار تطبيق حدث-بناء غير متزامن النقش عند:

• لا يحتاج العملاء للفصل الدراسي WaitHandleو IAsyncResultالكائنات متوفر ل غير متزامن العمليات، مما يعني أن الاستقصاء و WaitAllأو WaitAnyبحاجة إلى أن بناء بالعميل.

• تريد غير متزامن العمليات لإدارتها من قبل العميل باستخدام نموذج حدث/المفوض مألوفة.

أي عملية يتم ترشيحه غير متزامن يجب اعتبارها التنفيذ، ولكن تلك التي تتوقع تتطلب latencies طويلة. تكون مناسبة خاصة العمليات التي يقوم العملاء باستدعاء أسلوب و إعلام تشغيل الاكتمال، مع أي تدخل إضافية مطلوبة. كما المناسبة العمليات التي تقوم بتشغيل بشكل مستمر، دورياً بإعلام عملاء تقدم، تزايدي نتائج، أو الولاية التغييرات.

ل المزيد المعلومات حول تحديد متى يمكنك دعم يستند إلى حدث "غير متزامن النقش"، راجع تحديد متى يتم تنفيذه نقش غير متزامن يستند إلى حدث.

تسمية وظائف غير متزامن

لكل أسلوب متزامن MethodName التي تحتاج إلى توفير غير متزامن النسخة المطابقة:

Define a MethodNameAsync method that:

• و يتم إرجاع void.

• يأخذ المعلمات نفس كـ MethodName الأسلوب.

• يقبل invocations متعددة.

تعريف حالات MethodNameAsync التحميل، مماثلة إلى MethodNameAsync، ولكن مع إضافى valued على كائن معلمة تسمى userState. القيام بذلك أثناء تحضيرها لإدارة عدة invocations المتزامنة من الخاص بك أسلوب، في هذه الحالة userStateالقيمة التي سيتم تسليم إلى الجميع معالجات الأحداث لتمييز invocations من أسلوب. يمكنك أيضا اختيار إلى بذلك بساطة كمكان إلى sإلىre الولاية مستخدم لاسترداد أحدث.

For each separate MethodNameAsync method signature:

1. قم بتعريف حدث التالي في نفس فئة كالأسلوب:

   Public Event MethodNameCompleted As MethodNameCompletedEventHandler
   

   public event MethodNameCompletedEventHandler MethodNameCompleted;
   

2. قم بتعريف ما يلي تفويض و AsyncCompletedEventArgs. هذه من المحتمل أن يتم تعريف خارج هذه فئة نفسه، ولكن في نفس مساحة الاسم.

   Public Delegate Sub MethodNameCompletedEventHandler( _
       ByVal sender As Object, _
       ByVal e As MethodNameCompletedEventArgs)
   
   Public Class MethodNameCompletedEventArgs
       Inherits System.ComponentModel.AsyncCompletedEventArgs
   Public ReadOnly Property Result() As MyReturnType
   End Property
   

   public delegate void MethodNameCompletedEventHandler(object sender, 
       MethodNameCompletedEventArgs e);
   
   public class MethodNameCompletedEventArgs : System.ComponentModel.AsyncCompletedEventArgs
   {
       public MyReturnType Result { get; }
   }
   

   • تأكد من أن من MethodNameCompletedEventArgs فئة كشف أعضائها كخصائص للقراءة فقط، وليس حقول كحقول منع ربط بيانات.

   • قم بتعريف لا أي AsyncCompletedEventArgs-اشتقاق الفئات للأساليب التي لا ينتج عن نتائج. بساطة استخدم مثيل AsyncCompletedEventArgsنفسه.

     ملاحظة
     هو تماما مقبولة، عندما feasible والمناسبة لإعادة استخدام المفوض و AsyncCompletedEventArgsأنواع.في هذه الحالة، تسمية لن تكون كما يتوافق مع اسم الأسلوب، منذ المفوض معطى و AsyncCompletedEventArgsلن تكون مرتبطة إلى أسلوب مفرد.

بشكل اختياري دعم الإلغاء

إذا كان سيعتمد يتم إلغاء الأمر فئة غير متزامن كشف عمليات اليتم إلغاء الأمر يجب أن تكون تلك إلى العميل كما هو موضح أدناه. لاحظ أن هناك نقطتين القرارات التي تحتاج إلى يمكن الوصول إليه من قبل تعريف الدعم الإلغاء:

• فئة، بما في ذلك الإضافات المتوقعة المستقبلية، لدى أحد غير متزامن العملية يدعم الإلغاء؟

• يمكنك غير متزامن يدعم العمليات التي تدعم إلغاء العمليات المعلقة متعددة؟ أن هو، هل أخذ MethodNameAsync أسلوب userStateمعلمة، والسماح invocations متعددة قبل انتظار لأي ل finهوh؟

استخدم الإجابات إلى هذه الأسئلة الثاني في الجدول أدناه إلى تحديد ما يجب أن يكون توقيع لأسلوب الإلغاء الخاص بك.

Visual Basic

	العديد من العمليات التلقائية المعتمدة	واحد فقط تشغيل في وقت
متزامن واحد تشغيل في فئة بأكمله	Sub MethodNameAsyncCancel(ByVal userState As Object)	Sub MethodNameAsyncCancel()
عدة "العمليات المتزامن" في فئة	Sub CancelAsync(ByVal userState As Object)	Sub CancelAsync()

C#‎

	العديد من العمليات التلقائية المعتمدة	واحد فقط تشغيل في وقت
متزامن واحد تشغيل في فئة بأكمله	void MethodNameAsyncCancel(object userState);	void MethodNameAsyncCancel();
عدة "العمليات المتزامن" في فئة	void CancelAsync(object userState);	void CancelAsync();

إذا قمت بتعريف CancelAsync(object userState) الأسلوب، العملاء يجب أن تتوخى الحذر عند اختيار قيمها حالة إلى يجعلها قادرة تشغيل التمييز بين الجميع الأساليب غير متزامن استدعاء تشغيل الكائن، وليس فقط بين invocations الجميع من مفرد الأسلوب غير المتزامن.

decهوion لتسمية واحدة المتزامن عملية الإصدار من MethodNameAsyncCancel هو استناداً إلى إمكانية dهوcover الأسلوب في بيئة تصميم مثل Intellهوense Vهوual Studio الخاص بسهولة. هذا إلى تجميع أعضاء ذات الصلة وتميز بها عن الأعضاء الآخرين والتي تحتوي على أي شيء ب غير متزامن الأداء الوظيفي. إذا كنت تتوقع أن احتمال وجود إضافى العمليات غير المتزامنة إضافتها في الإصدارات اللاحقة، فمن الأفضل تعريف CancelAsync.

لا بتعريف وظائف متعددة من الجدول أعلاه في نفس الفئة. التي سوف لا معنى، أو أنه سوف ازدحام واجهة فئة باستخدام proliferation من وظائف.

هذه الطرق عادة سيعود فورا، وقد تشغيل أو قد لا بالفعل إلغاء الأمر. في معالج الحدث للحدث MethodNameCompleted ، يتضمن الكائن MethodNameCompletedEventArgs Cancelledالحقل، يمكن للعملاء استخدام إلى لتحديد ما إذا كان الإلغاء حدث.

يلتزم بواسطة دلالات الإلغاء في أفضل الممارسات لتطبيق حدث-إلى نقش غير متزامن.

بشكل اختياري دعم خاصية IsBusy

إذا لم يكن فئة دعم invocations المتزامنة المتعددة، يجب مراعاة تعريض على IsBusyخاصية. Th هو يسمح للمطورين لتحديد ما إذا كان MethodNameAsync الطريقة هو قيد التشغيل بدون catching استثناء من MethodNameAsync الأسلوب.

يلتزم بواسطة IsBusyدلالات الموصوفة في أفضل الممارسات لتطبيق حدث-إلى نقش غير متزامن.

بشكل اختياري توفير دعم لتقرير عن التقدم

كان مطلوباً بشكل متكرر غير متزامن العملية لتقرير التقدم أثناء التشغيل. يوفر "نقش غير متزامن" يستند إلى حدث إرشاد للقيام بذلك.

• تعريف حدث إلى أن يتم تشغيل الحدث غير متزامن العملية وقم باستدعاء تشغيل مؤشر ترابط المناسبة. ProgressChangedEventArgsيحمل كائن مؤشر تقدم valued على العدد الصحيح الذي هو من المتوقع أن يكون بين 0 و 100.

• قم بتسمية هذا حدث كـ التالي:

  • ProgressChangedإذا كان الفئة متعددة غير متزامن العمليات (أو من المتوقع أن تتسع لتشمل متعددة غير متزامن العمليات في الإصدارات المستقبلية)؛

  • MethodNameProgressChanged إذا كان يحتوي الفئة واحدة غير متزامن العملية.

  الاختيار هذه التسمية parallels إجراؤها للأسلوب الإلغاء، كـ الموصوفة في مقطع "إلغاء الدعم" بشكل اختياري.

هذا حدث يجب أن استخدم ProgressChangedEventHandlerتوقيع المفوض و ProgressChangedEventArgsفئة. بدلاً من ذلك، إذا كان أكثر المجالات الخاصة التقدم ويمكن توفير مؤشر (لمثيل قراءة وحدات البايت وإجمالي وحدات البايت لعملية ينزّل)، ثم يجب أن تقوم بتعريف فئة مشتقة من ProgressChangedEventArgs.

لاحظ أن هناك هو واحد فقط MethodNameProgressChanged حدث أوProgressChanged للفئة، بغض النظر عن العدد غير متزامن الأساليب التي يعتمدها. يتم توقع العملاء لاستخدام userStateالكائن الذي هو التي تم تمريرها إلى وظائف MethodNameAsync من ل dهوtinguهوh بين تحديثات التقدم في العديد من العمليات المتزامنة.

قد تكون هناك حالات في أي العمليات متعددة دعم التقدم وبعضها بإرجاع مؤشر مختلفة للتقدم. في ترتيب هو الحالة واحدة ProgressChangedحدث هو غير مناسب، وقد ترغب في دعم متعدد ProgressChangedالأحداث. في هذا حالة استخدام نموذج تسمية من من MethodNameProgressChanged لكل MethodNameAsync الأسلوب.

يلتزم بالإعلام التقدم عن دلالات الموصوفة أفضل الممارسات لتطبيق حدث-إلى نقش غير متزامن.

بشكل اختياري توفير دعم لإرجاع نتائج تزايدي

أحياناً غير متزامن يمكن أن ترجع العملية نتائج تزايدي قبل الاكتمال. هناك عدد من الخيارات التي يمكن أن تستخدم إلى يعتمد هذا السيناريو. تتبع بعض الأمثلة.

مفرد-عملية فئة

إذا كان فئة باعتماد واحدة فقط غير متزامن تشغيل، ويكون قادراً على نتائج المتزايد، ثم تشغيل:

• توسيع ProgressChangedEventArgsنوع لحمل تزايدي ينتج عن بيانات وتعريف حدث MethodNameProgressChanged من ذلك توسيع بيانات.

• $ $ $ $ th هو حدث MethodNameProgressChanged عند هناك هو نتيجة متزايد للتقرير.

يطبق هذا الحل خاصة لفصل دراسي مفرد متزامن العملية لأن هناك مشكلة مع نفس حدث التي تحدث لإرجاع تزايدي النتائج تشغيل "كافه العمليات"، كما يفعل حدث MethodNameProgressChanged.

فئة متعددة-تشغيل مع نتائج تزايدي متجانس

في هذه الحالة، يعتمد فئة متزامنة وظائف متعددة، كل قادر على إرجاع تزايدي نتائج، وتلك تزايدي الجميع نتائج تحتوي على نفس نوع بيانات.

اتبع الطراز الموضح أعلاه لفئات تشغيل بمفرده، كما نفس EventArgsبنية ستعمل لكافة نتائج المتزايد. Define a ProgressChanged حدث instead of a MethodNameProgressChanged حدث, since it applies إلى multiple غير متزامن وظائف.

Multiple-تشغيل فئة مع Heterogeneous تزايدي نتائج

If your فئة supports multiple غير متزامن وظائف, each returning a different نوع of بيانات, you should:

• Separate your تزايدي النتيجة التقارير من your التقدم التقارير.

• Define a separate MethodNameProgressChanged حدث مع appropriate EventArgs for each غير متزامن أسلوب إلى مؤشر that أسلوب's تزايدي النتيجة بيانات.

Invoke that معالج الأحداث تشغيل the appropriate مؤشر ترابط كـ described في أفضل الممارسات لتطبيق حدث-إلى نقش غير متزامن.

Hوling مخرج و المرجع معلمات في وظائف

Although the استخدم of out و ref هو, في عام, discouraged في the .NET Framework, هنا are the rules إلى follow when they are موجود:

Given a متزامن أسلوب MethodName:

• out معلمات إلى MethodName should not be part of MethodNameAsync. بدلاً من ذلك، يجب أن يكونوا جزءا من MethodNameCompletedEventArgs يحمل نفس الاسم كمعلمة به يعادل في MethodName (unless there هو a more appropriate name).

• refإلى المعلماتMethodاسم يجب أن تظهر كجزء من من MethodاسمAsync، وكجزء من MethodاسمCompletedEventArgs يحمل نفس الاسم كمعلمة به يعادل في Methodاسم (unless there هو a المزيد appropriate اسم).

ل مثال، معين:

Public Function MethodName(ByVal arg1 As String, ByRef arg2 As String, ByRef arg3 As String) As Integer

public int MethodName(string arg1, ref string arg2, out string arg3);

الأسلوب غير المتزامنة الخاصة بك و به AsyncCompletedEventArgsفئة تبدو كما يلي:

Public Sub MethodNameAsync(ByVal arg1 As String, ByVal arg2 As String)

Public Class MethodNameCompletedEventArgs
    Inherits System.ComponentModel.AsyncCompletedEventArgs
    Public ReadOnly Property Result() As Integer 
    End Property
    Public ReadOnly Property Arg2() As String 
    End Property
    Public ReadOnly Property Arg3() As String 
    End Property
End Class

public void MethodNameAsync(string arg1, string arg2);

public class MethodNameCompletedEventArgs : System.ComponentModel.AsyncCompletedEventArgs
{
    public int Result { get; };
    public string Arg2 { get; };
    public string Arg3 { get; };
}

راجع أيضًا:

المهام

كيفية القيام بما يلي: تنفيذ مكوّن التي تعتمد على النقش غير متزامن يستند إلى حدث

كيفية القيام بما يلي: تشغيل عملية في الخلفية

كيفية القيام بما يلي: تنفيذ النماذج التي تستخدم عملية الخلفية

المرجع

ProgressChangedEventArgs

AsyncCompletedEventArgs

المبادئ

تحديد متى يتم تنفيذه نقش غير متزامن يستند إلى حدث

أفضل الممارسات لتطبيق حدث-إلى نقش غير متزامن

موارد أخرى

ذات مؤشرات ترابط متعددة البرمجة بالأحداث المستندة إلى نمط غير متزامن