Winton.Extensions.Configuration.Consul

winton.extensions.configuration.consul

เพิ่มการสนับสนุนสำหรับการกำหนดค่าแอปพลิเคชัน. NET Core โดยใช้กงสุล ใช้งานได้ดีกับ Git2Consul

สารบัญ

• การติดตั้ง
• การใช้งาน
  • การตั้งค่าขั้นต่ำ
  • ตัวเลือก
• กำหนดค่าตัวเลือกการแยกวิเคราะห์
  • ค่ากงสุลคือ JSON
  • ค่ากงสุลคือสเกลาร์
  • ค่ากงสุลเป็นการผสมผสานของ JSON และสเกลาร์
  • การปรับแต่งกลยุทธ์ 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 มีโอเวอร์โหลดพร้อมพารามิเตอร์ที่สามเพิ่มเติมของ 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 และสเกลาร์

หากคุณต้องการสนับสนุนทั้งคีย์ที่ขยายและค่า 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 ดังนั้นจึงกลายเป็นความรับผิดชอบของคุณในการใช้งานตามสถานการณ์ที่คุณต้องการ