باستخدام DbTool لقاعدة بيانات البذور في تطبيقات .NET (الأساسية)

نقدم انتباهكم إلى DbTool - أداة مساعدة لسطر الأوامر لتصدير بيانات قاعدة البيانات إلى تنسيقات مختلفة ومكتبة Korzh.DbUtils مفتوحة المصدر ، والتي يمكن استخدامها تبسيطًا كبيرًا "البذر" الأولي لقاعدة البيانات في تطبيق .NET (Core).

باستخدام مجموعة الأدوات هذه ، يمكنك:

1. احفظ البيانات من قاعدة البيانات المحلية الخاصة بك إلى ملفات بتنسيق نصي معين (XML ، JSON) ، والتي يسهل توصيلها بالمشروع.
2. استخدم الملفات المحفوظة لملء قاعدة بيانات التطبيق نفسه في بدايتها الأولى.

فيما يلي سوف أخبرك لماذا كل هذا ضروري ، وكيفية تثبيت هذه الأدوات وتكوينها ووصف سيناريو مفصل لاستخدامها.

لماذا فعلنا DbTool

كانت المهمة الأولية هي إنشاء آلية ملائمة لملء قاعدة البيانات في تطبيقات .NET (Core). نظرًا لخصائص نوع نشاطنا (تطوير المكونات) ، غالبًا ما نحتاج إلى إنشاء تطبيقات نموذجية صغيرة تعرض ميزة أو أخرى من ميزات منتجنا. يجب أن تعمل مثل هذه المشروعات التجريبية مع قاعدة بيانات اختبار معينة ، وبالتالي يُنصح بإنشاء قاعدة البيانات هذه وتعبئتها تلقائيًا في بداية التطبيق لأول مرة.

إذا كان المشروع يستخدم Entity Framework (Core) (وغالبًا ما يحدث) ، فلا توجد مشاكل في إنشاء قاعدة البيانات. يمكنك ببساطة استدعاء dbContext.Database.EnsureCreated أو dbContext.Database.Migrate (إذا كان من المهم الاحتفاظ dbContext.Database.Migrate ).

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

المشكلة المحتملة الثانية هي ترحيل قاعدة البيانات نفسها. من وقت لآخر ، هناك حاجة لتغيير بنية قاعدة البيانات قليلاً (إضافة حقل جديد أو حذف أو إعادة تسمية الحقل القديم أو إضافة علاقة جديدة بين الجداول وما إلى ذلك). عادةً ما يصبح البرنامج النصي SQL الذي تم إنشاؤه ضمن الهيكل القديم غير ذي صلة في هذه الحالة ويتسبب تنفيذه في حدوث خطأ. أثناء تحميل البيانات من تنسيق تابع لجهة أخرى ، لا توجد مشاكل. يتم تخطي الحقول الجديدة / التي تم تغييرها. توافق على أنه لأغراض العرض التوضيحي ، من الأفضل أن يبدأ البرنامج ، وإن كان بدون بيانات في بعض الحقول الجديدة ، إلا أنه لا يبدأ على الإطلاق.

نتيجة لذلك ، توصلنا إلى الحل التالي:

1. يتم تسجيل البيانات من "نسخة رئيسية" من قاعدة البيانات التجريبية لدينا في ملف بتنسيق معين "مستقل" (حاليا هو XML أو JSON). يتم تسليم الملفات الناتجة (أو ملف أرشيف واحد) مع المشروع. هذه المهمة ، في الواقع ، تتعامل مع DbTool.
2. يتم إدخال جزء صغير من التعليمات البرمجية في برنامجنا ، والذي ، باستخدام الفئات والوظائف في مكتبة Korzh.DbUtils ، يملأ قاعدة البيانات ببيانات من الملف (الملفات) التي تم الحصول عليها في الخطوة الأولى.
   بالإضافة إلى السيناريو أعلاه ، يمكن استخدام DbTool ببساطة لتصدير البيانات إلى تنسيقات أخرى ونقل البيانات بين قواعد البيانات. لذلك ، على سبيل المثال ، يمكنك تحميل البيانات من قاعدة البيانات الخاصة بك إلى SQL Server ثم تحميلها في قاعدة بيانات مماثلة في MySQL

تركيب

يتم تطبيق DbTool كأداة عمومية .NET Core ، أي يمكن تثبيتها بسهولة على أي نظام حيث يوجد .NET SDK الإصدار 2.1 أو أعلى.

لتثبيت الأداة المساعدة ، تحتاج فقط إلى فتح وحدة التحكم (Terminal / Command Prompt) وتشغيل الأمر التالي:

 dotnet tool install -g Korzh.DbTool 

للتحقق بعد التثبيت ، اكتب dbtool في وحدة التحكم وسترى مساعدة مع قائمة الأوامر المتاحة.

إضافة اتصال إلى قاعدة البيانات

لبدء العمل مع DbTool ، تحتاج إلى إضافة اتصال قاعدة بيانات:

 dbtool add {YourConnectionId} {DbType} {YourConnectionString} 

هنا:

• {YourConnectionId} هو معرف تريد تعيينه لهذا الاتصال بحيث يمكنك الوصول إليه لاحقًا عند تشغيل أوامر أخرى.
• DbType هو نوع DBMS الخاص بك. في وقت كتابة هذا التقرير ، كان DbTool (الإصدار 1.1.7) يدعم قواعد بيانات SQL Server (mssql) و MySQL (mysql).
• المعلمة الأخيرة في هذا الأمر هي سلسلة الاتصال. نفس الشيء الذي تستخدمه بالفعل في مشروع .NET (Core).

مثال:

بعد ذلك ، يمكنك التحقق من جميع اتصالاتك عن طريق الكتابة:

 dbtool connections list 

تصدير البيانات

الآن وقد أضفنا الاتصال ، يمكننا تصدير قاعدة البيانات الخاصة بنا باستخدام أمر التصدير:

 dbtool export {ConnectionId} [--format=xml|json] [--output={path-to-folder}] [--zip={file-name}] 

قد يتم حذف أي خيار مذكور أعلاه. إذا لم تحدد format فسيتم استخدام JSON. إذا حذفت خيار output ، فسيتم وضع النتيجة في دليل النموذج ConnectionId_yyyy-MM-dd في نموذج غير مغلف.

على سبيل المثال ، الأمر التالي:

 dbtool export MyDb01 --zip=MyDbData.zip 

سيتم إنشاء أرشيف ZIP باسم MyDbData.zip في الدليل الحالي وملؤه بملفات البيانات بتنسيق JSON (ملف واحد لكل جدول قاعدة بيانات).

استيراد البيانات

يمكنك استيراد البيانات التي تم إنشاؤها في الخطوة السابقة إلى قاعدة البيانات الخاصة بك. أو إلى أي قاعدة أخرى مع نفس الهيكل.

هام: لا يقوم DbTool بإنشاء جداول أثناء عملية الاستيراد. وبالتالي ، يجب أن تكون قاعدة البيانات التي يتم استيراد البيانات إليها موجودة بالفعل وأن يكون لها نفس البنية (أو على الأقل مماثلة) مثل البنية الأصلية.

أمر الاستيراد نفسه كالتالي:

 dbtool import {ConnectionId} [--input=path-to-file-or-folder] [--format=xml|json] 

يخبر خيار --input الأداة المساعدة عن مكان البحث عن البيانات المستوردة. إذا تم تحديد مسار مجلد ، فسيستورد DbTool ملفات .xml أو .json في هذا المجلد. إذا كان هذا ملفًا بتنسيق ZIP ، فستقوم الأداة أولاً بفك ضغط هذا الأرشيف ومن هناك يتم سحب ملفات البيانات الضرورية.

كما في الحالة السابقة ، يمكن حذف - format لأن DbTool يمكنه التعرف على التنسيق بواسطة امتدادات الملفات.

مثال:

 dbtool import MyDb01 --input=MyDbData.zip 

مكتبة Korzh.DbUtils

الأداة المساعدة DbTool نفسها مبنية على أساس Korzh.DbUtils مكتبة مفتوحة المصدر ، والتي تتضمن عدة حزم مع تنفيذ بعض عمليات قاعدة البيانات الأساسية.

Korzh.DbUtils

يحدد التجريدات الأساسية والواجهات مثل IDatasetExporter و IDatasetImporter و IDataPacker و IDbBridge

Korzh.DbUtils.Import

يحتوي على تطبيقات واجهات IDatasetImporter لتنسيقات XML و JSON. بالإضافة إلى ذلك ، تتضمن هذه الحزمة فئة DbInitializer ، والتي يمكنك استخدامها لنشر البيانات في مشاريعك (المزيد حول هذا أدناه).

Korzh.DbUtils.Export

يحتوي على تطبيقات IDatasetExporter لـ XML و JSON.

Korzh.DbUtils.SqlServer

يحتوي على تطبيق واجهات عمليات قاعدة البيانات الأساسية (IDbBridge ، IDbReader ، IDbSeeder) لـ MS SQL Server.

Korzh.DbUtils.MySQL

يحتوي على تطبيقات واجهات قاعدة البيانات لماي.

هنا يمكنك العثور على المرجع الكامل في مكتبة Korzh.DbUtils API .

باستخدام Korzh.DbUtils لملء قاعدة البيانات مع البيانات عند بدء تشغيل التطبيق

الآن ، في الواقع ، سوف ننظر في كيفية استخدام DbTool و Korzh.DbUtils لتطبيق البرنامج النصي الأساسي لملء (البذر) قاعدة البيانات عند الإطلاق الأول للتطبيق.

افترض أن لديك "نسخة رئيسية" من بعض قواعد البيانات التي تحتاج إلى "نسخ" على كمبيوتر المستخدم عند بدء تشغيل التطبيق لأول مرة.

الخطوة 1: تصدير النسخة الرئيسية إلى JSON

فقط قم بتثبيت DbTool ، كما هو موضح أعلاه ، قم بإضافة اتصال إلى قاعدة البيانات ثم قم بتشغيل الأمر export لحفظ جميع البيانات من قاعدة البيانات هذه في مجلد منفصل:

 dotnet tool install -g Korzh.DbTool dbtool connections add MyMasterDb mssql "{ConnectionString}" dbtool export MyMasterDb 

الخطوة 2: إضافة ملفات البيانات إلى مشروعنا

بعد الخطوة السابقة ، لدينا مجلد جديد من النموذج MyMasterDb-yyyy-MM-dd ، مع مجموعة من ملفات JSON (واحد لكل جدول). ما عليك سوى نسخ محتويات هذا المجلد إلى App_Data \ DbSeed لمشروعنا .NET (Core). يرجى ملاحظة أنه بالنسبة للمشروعات ضمن .NET Framework ، ستحتاج أيضًا إلى إضافة هذه الملفات يدويًا إلى المشروع.

الخطوة 3: رمز تهيئة DB

على الرغم من أن العملية نفسها (بحد أقصى بعض التفاصيل) قابلة للتطبيق على أي نوع من المشاريع ضمن .NET Core أو .NET Framework (الإصدار 4.6.1 أو أعلى) ، ولتبسيط الوصف ، افترض أننا نتحدث عن مشروع ASP.NET Core يعمل مع يتم إنشاء قاعدة بيانات SQL Server وأن قاعدة البيانات هذه تلقائيًا باستخدام Entity Framework Core.

وبالتالي ، لحل مشكلة ملء قاعدة البيانات بالبيانات في البداية ، نحتاج إلى:

1. قم بتثبيت حزم مكتبة Korzh.DbUtils في مشروع NuGet

في هذه الحالة ، نحتاج إلى 2 منهم:

• Korzh.DbUtils.Import
• Korzh.DbUtils.SqlServer

2. إضافة رمز التهيئة

فيما يلي مثال على هذه التعليمة البرمجية التي يجب أن نضيفها في نهاية طريقة بدء التشغيل. تكوين:

 public void Configure(IApplicationBuilder app, IHostingEnvironment env) { . . . . app.UseMvc(); using (var scope = app.ApplicationServices.GetRequiredService<IServiceScopeFactory>().CreateScope()) using (var context = scope.ServiceProvider.GetService<AppDbContext>()) { if (context.Database.EnsureCreated()) { //run only if database was not created previously Korzh.DbUtils.DbInitializer.Create(options => { options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")); //set the connection string for our database options.UseFileFolderPacker(System.IO.Path.Combine(env.ContentRootPath, "App_Data", "SeedData")); //set the folder where to get the seeding data }) .Seed(); } } } 

لجعل كل شيء جميلًا ، أو إذا كنت بحاجة إلى إجراء بعض التهيئة الإضافية في البداية الأولى (على سبيل المثال ، إضافة حسابات مستخدمين متعددة و / أو أدوار المستخدم) ، فمن الأفضل ترتيب كل هذا الرمز كطريقة امتداد منفصلة (دعنا نسميها EnsureDbInitialized ) للواجهة IApplicationBuilder .

يمكن العثور على مثال لهذا التطبيق على GitHub في المشروع التجريبي لمكتبة EasyQuery .

في هذه الحالة ، تحتاج فقط إلى إضافة مكالمة واحدة في نهاية طريقة بدء التشغيل. تكوين:

 public void Configure ( IApplicationBuilder,   IHostingEnvironment) { . . . . app.UseMvc (); //Init database (only if necessary) app.EnsureDbInitialized(Configuration, env); } 

الخطط المستقبلية

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

من التحسينات المحتملة ، نرى ما يلي:

• دعم قواعد البيانات الأخرى (PostgreSQL ، Oracle ، SQLite ، MariaDB)

  
  

• التنسيقات الجديدة التي يمكنك تصدير البيانات إليها (CSV و Excel و HTML)

  
  

• تشغيل نسخ البيانات مباشرة من قاعدة البيانات إلى قاعدة البيانات (الآن يمكن تنفيذها من خلال مكالمات متتالية لتصدير / استيراد الأوامر)

  
  

• عمليات النسخ الاحتياطي / الاستعادة الكاملة مع الحفاظ الكامل على بنية قاعدة البيانات وإنشائها من البداية أثناء الاسترداد.

  
  

سنكون سعداء لسماع أي اقتراحات أو تعليقات وسنكون ممتنين جدًا للنجوم الجدد لمستودع مكتبة جيثب :)

شكرا لاهتمامكم!