Winton.Extensions.Configuration.Consul

winton.extensions.configuration.consul

يضيف دعمًا لتكوين تطبيقات .NET Core باستخدام Consul. يعمل بشكل رائع مع GIT2CONSUL.

محتويات

• تثبيت
• الاستخدام
  • الحد الأدنى من الإعداد
  • خيارات
• تكوين خيارات التحليل
  • قيم القنصل json
  • قيم القنصل هي عدد سكان
  • قيم القنصل هي مزيج من JSON و Neadars
  • تخصيص استراتيجية ConvertConsulKVPairToConfig

تثبيت

إضافة Winton.Extensions.Configuration.Consul إلى تبعيات مشروعك ، إما عبر مدير حزمة Nuget أو PackageReference في ملف CSPROJ.

الاستخدام

الحد الأدنى من الإعداد

توفر المكتبة طريقة تمديد تسمى AddConsul لـ IConfigurationBuilder بالطريقة نفسها التي يقوم بها مقدمو التكوين الآخرين. عادة ما يتم تكوين IConfigurationBuilder في فئة Program أو Startup لتطبيق ASP.NET Core. راجع وثائق Microsoft لمزيد من المعلومات حول IConfigurationBuilder .

يظهر مثال أدنى أدناه:

 builder
    . AddConsul ( $ " { env . ApplicationName } / { env . EnvironmentName } " ) ;

على افتراض أن التطبيق يعمل في بيئة "التطوير" واسم التطبيق هو "موقع الويب" ، فإن هذا سيقوم بتحميل كائن تكوين JSON من مفتاح Website/Development في القنصل.

خيارات

يحتوي AddConsul على حمولة زائدة مع معلمة ثالثة إضافية من Type Action<IConsulConfigurationSource> والتي تسمح بتعيين الخيارات الموضحة أدناه.

• ConsulConfigurationOptions

  Action<ConsulClientConfiguration> يمكن استخدامه لتكوين عميل القنصل الأساسي.

• ConsulHttpClientHandlerOptions

  Action<HttpClientHandler> الذي يمكن استخدامه لتكوين خيارات معالج HTTP الخاصة بعميل القنصل الأساسي.

• ConsulHttpClientOptions

  Action<HttpClient> يمكن استخدامه لتكوين خيارات HTTP الخاصة بعميل القنصل الأساسي.

• KeyToRemove

  جزء من مفتاح القنصل لإزالته من مفاتيح التكوين. بشكل افتراضي ، عند تحليل التكوين ، يتم إنشاء المفاتيح عن طريق إزالة مفتاح الجذر في القنصل حيث يوجد التكوين. هذا الافتراضات إلى Key .

• OnLoadException

  Action<ConsulLoadExceptionContext> يمكن استخدامه لتكوين كيفية معالجة الاستثناءات التي تم إلقاؤها أثناء التحميل الأول.

• OnWatchException

  Func<ConsulWatchExceptionContext, TimeSpan> يمكن استخدامه لتكوين كيفية إلقاء الاستثناءات عند مشاهدة التغييرات. يتم استخدام TimeSpan التي يتم إرجاعها لتعيين تأخير قبل إعادة المحاولة. يوفر ConsulWatchExceptionContext البيانات التي يمكن استخدامها لتنفيذ استراتيجية التراجع أو إلغاء المشاهدة تمامًا.

• Optional

  bool يشير إلى ما إذا كان التكوين اختياريًا. إذا كان false ، فسيتم رميه أثناء الحمل الأول إذا كان التهيئة مفقودة للمفتاح المحدد. الإعدادات الافتراضية إلى false .

• Parser

  المحلل الذي يجب استخدامه ، والذي يجب أن يتطابق مع تنسيق التكوين المخزن في القنصل. الإعدادات الافتراضية إلى JsonConfigurationParser . إما استخدام تلك تحت Winton.Extensions.Configuration.Consul.Parsers أو إنشاء خاص بك عن طريق تنفيذ IConfigurationParser .

• PollWaitTime

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

• ReloadOnChange

  bool يشير إلى ما إذا كان سيتم إعادة تحميل التكوين عندما يتغير في القنصل. إذا كان ذلك true ، فسيشاهد المفتاح الذي تم تكوينه للتغييرات. عندما يحدث تغيير ، سيتم إعادة تحميل التكوين بشكل غير متزامن وسيتم تشغيل IChangeToken للإشارة إلى أن التكوين قد تم إعادة تحميله. الإعدادات الافتراضية إلى false .

• ConvertConsulKVPairToConfig

  Func<KVPair, IEnumerable<KeyValuePair<string, string>>> الذي يمنحك تحكمًا كاملاً في تحليل مفاتيح القنصل المؤهلة تمامًا وقيم القنصل الخام ؛ سوف التنفيذ الافتراضي:

  • استخدم Parser الذي تم تكوينه لتحليل قيم القنصل
  • قم بإزالة بادئة KeyToRemove التي تم تكوينها من مفاتيح القنصل

  ومع ذلك ، عند تعيين هذا العضو ، يمكنك تجاوز المفتاح الافتراضي ومعالجة القيمة ، ولا يتمتع Parser و KeyToRemove بأي تأثير ما لم تكن وظيفة ConvertConsulKVPairToConfig تستخدمها.

تكوين خيارات التحليل

قيم القنصل json

بشكل افتراضي ، سيقوم موفر التكوين هذا بتحميل جميع أزواج القيمة الرئيسية من القنصل ضمن مفتاح الجذر المحدد ، ولكنه يفترض افتراضيًا أن قيم مفاتيح الأوراق يتم ترميزها على أنها JSON.

خذ المثال التالي لمثيل معين لمتجر القنصل KV:

 - myApp/
    - auth/
        {
            "appId": "guid",
            "claims": [
                "email",
                "name"
            ]
        }
    - logging/
        {
            "level": "warn"
        }

في هذه الحالة ، يمكننا إضافة القنصل كمصدر تكوين مثل SO:

 var configuration = builder
    . AddConsul ( "myApp" , cancellationToken )
    . Build ( ) ;

سيحتوي التكوين الناتج على أقسام auth logging . كمثال ملموسة configuration.GetValue<string>("logging:level") ستعيد "warn" و configuration.GetValue<string>("auth:claims:0") سيعود "email" .

قيم القنصل هي عدد سكان

ومع ذلك ، في بعض الأحيان ، يتم تخزين التكوين في القنصل كمجموعة من المفاتيح الموسعة. على سبيل المثال ، أدوات مثل consul-cli Load Config في هذا التنسيق.

يمكن اعتبار التكوين في هذه الحالة كشجرة تحت مفتاح جذر معين في القنصل. على سبيل المثال ، الاستمرار في المثال أعلاه ، سيتم تخزين التكوين على النحو التالي:

 - myApp/
    - auth/
        - appId/
            "guid"
        - claims/
            0/
                "email"
            1/
                "name"
    - logging/
        - level/
            "warn"

كما هو موضح أعلاه ، يتعامل مزود التكوين هذا مع المفاتيح العودية افتراضيًا. الفرق الوحيد هنا هو أن القيم لم تعد مشفرة على أنها JSON. لذلك ، من أجل تحميل هذا التكوين ، يجب تغيير المحلل. يمكن القيام بذلك مثل ذلك عند إضافة مزود التكوين:

 builder
    . AddConsul (
        "myApp" ,
        options =>
        {
            options . Parser = new SimpleConfigurationParser ( ) ;
        } ) ;

يتوقع SimpleConfigurationParser مواجهة قيمة العددية في كل مفتاح ورقة في الشجرة.

قيم القنصل هي مزيج من JSON و Neadars

إذا كنت بحاجة إلى دعم كل من المفاتيح الموسعة وقيم JSON ، فيمكن تحقيق ذلك بوضعها تحت مفاتيح الجذر المختلفة وإضافة مصادر تكوين متعددة. على سبيل المثال:

 builder
    . AddConsul (
        "myApp/expandedKeys" ,
        options =>
        {
            options . Parser = new SimpleConfigurationParser ( ) ;
        } )
    . AddConsul ( "myApp/jsonValues" , cancellationToken ) ;

تخصيص استراتيجية ConvertConsulKVPairToConfig

في بعض الأحيان ، قد تحتاج إلى مزيد من التحكم في تحويل أزواج القنصل KV الخام إلى بيانات IConfiguration . في هذه الحالة ، يمكنك تعيين وظيفة ConvertConsulKVPairToConfig المخصصة:

 builder
    . AddConsul (
        "myApp" ,
        options =>
        {
            options . ConvertConsulKVPairToConfig = kvPair =>
            {
                var normalizedKey = kvPair . Key
                    . Replace ( "base/key" , string . Empty )
                    . Replace ( "__" , "/" )
                    . Replace ( "/" , ":" )
                    . Trim ( '/' ) ;

                using Stream valueStream = new MemoryStream ( kvPair . Value ) ;
                using var streamReader = new StreamReader ( valueStream ) ;
                var parsedValue = streamReader . ReadToEnd ( ) ;

                return new Dictionary < string , string > ( )
                {
                    { normalizedKey , parsedValue }
                } ;
            } ;
        } ) ;

تحذير: من خلال تخصيص استراتيجية ConvertConsulKVPairToConfig ، يمكنك تجاوز أي احتجاج تلقائي Parser و KeyToRemove التي تم تكوينها ، بحيث تصبح مسؤوليتك في استخدامها حسب الحاجة من خلال السيناريو الخاص بك.