撰寫一個擴充套件將 ASP.NET MVC5 專案轉換成 .NET Core 3.1 的專案

圖片取自：https://stackoverflow.com/questions/5513708/vs-extensibility-architecture-package-api-visual-studio-library

前言

記得，在去年的 Taiwan .NET Conf 2019 的分享裡，我分享了一場『該準備從 .NET Framework 4.x 遷移到 .NET Core 3.0 的嗎？』因為分享的當下 .NET Core 3.1 還未推出，而在分享前，我除了思考當前企業所面臨的挑戰外，心裡也迸出一個想法就是，我何不撰寫一個能夠將 ASP.NET MVC 5 的專案直接轉換為 .NET Core 3 專案的擴充套件呢？因為一直以來，我都有在涉獵 VS Extensibility & VS Package 等開發，自身也有撰寫一些 VS 擴充套件，像是 MyORM Extensions ，也有推出 C# Project Templates 線上課程『團隊開發系列-設計符合團隊的範本精靈 (Project Template)』等等，也有上架在 VS Marketplace 上，於是在這場 Session 開始前兩個禮拜，便著手開始撰寫開發這個套件。

下方為當時的 Slides：


架構規劃

但因為時間非常有限，而我又必須先做出一個雛形，不過我希望在 VS 上的操作模式是：【我可以任意在任何一個 ASP.NET MVC 5 的專案點滑鼠右鍵隨即有個選單 "Convert MVC5 to .NET Core 3"】的 MenuItem

因此，我需要單鍵就可將 ASP.NET MVC 5 的專案轉換成 .NET Core 3 的專案類型。

關於 VS Pacakges

要做到這件事，不單單是像 MyORM 透過 IWizard 介面與 Project Templates 就可以實現，VS Extensibility SDK 中可開發的擴充套件提供了下面幾種類型：

  • Analyzer 
  • Project Templates 
  • Item Templates 
  • ToolbarControl 
  • VsPackages

若以部署來源來說，應該還有 Assembly 類型，而這些是可以緩和開發的，比如說，我可以開發一個 VS Toolbar Control 包含自定義視窗的 Project Templates 但是如果需要在 VS 增加按鈕或是選單透過 .vsct 描述檔案來定義，它是一個 XML 檔案，不過不管是 ToolbarControl 或是 MenuItem 若該事件處裡需與 VS 之間互動就得使用 VsPackages 的專案了。

程式撰寫

二話不說開始進行套件的開發，這邊 VS 2019 與 VS 2017 的操作順序稍有些不同，這邊我暫時以 VS 2019 為主。

  1. 建立 VSIX Project
  2. 建立 ConvertMvc5ToCore3CommandPackage.vsct
  3. 建立 ConvertMvc5ToCore3Command.cs 命令實作檔案
  4. 撰寫 ConvertMvc5ToCore3Command.InitializeAsync() 方法
  5. 決定 Execute 要做的事情

這邊得先解釋當你在 VS 點了自定義的按鈕或選單，VS 會呼叫 Execute 方法，該方法實作在 AsyncPackage 類別中，你可以將所有程式碼撰寫在 InitialzeAsync 裡，但我的習慣是會拆另外一個檔案，避免 VsPackage.cs 內容過於複雜難以管理。

初次建立的 VsPackage 的程式碼內容如下：

using System;
using System.ComponentModel.Design;
using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using System.Runtime.InteropServices;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.VisualStudio;
using Microsoft.VisualStudio.OLE.Interop;
using Microsoft.VisualStudio.Shell;
using Microsoft.VisualStudio.Shell.Interop;
using Microsoft.Win32;
using Task = System.Threading.Tasks.Task;

namespace ConvertMVC5ToCore3
{
    /// <summary>
    /// This is the class that implements the package exposed by this assembly.
    /// </summary>
    /// <remarks>
    /// <para>
    /// The minimum requirement for a class to be considered a valid package for Visual Studio
    /// is to implement the IVsPackage interface and register itself with the shell.
    /// This package uses the helper classes defined inside the Managed Package Framework (MPF)
    /// to do it: it derives from the Package class that provides the implementation of the
    /// IVsPackage interface and uses the registration attributes defined in the framework to
    /// register itself and its components with the shell. These attributes tell the pkgdef creation
    /// utility what data to put into .pkgdef file.
    /// </para>
    /// <para>
    /// To get loaded into VS, the package must be referred by &lt;Asset Type="Microsoft.VisualStudio.VsPackage" ...&gt; in .vsixmanifest file.
    /// </para>
    /// </remarks>
    [PackageRegistration(UseManagedResourcesOnly = true, AllowsBackgroundLoading = true)]
    [InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)] // Info on this package for Help/About
    [ProvideMenuResource("Menus.ctmenu", 1)]
    [Guid(ConvertMvc5ToCore3CommandPackage.PackageGuidString)]
    [SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1650:ElementDocumentationMustBeSpelledCorrectly", Justification = "pkgdef, VS and vsixmanifest are valid VS terms")]
    [ProvideAutoLoad(VSConstants.UICONTEXT.SolutionExists_string, PackageAutoLoadFlags.BackgroundLoad)]
    public sealed class ConvertMvc5ToCore3CommandPackage : AsyncPackage
    {
        /// <summary>
        /// ConvertMvc5ToCore3CommandPackage GUID string.
        /// </summary>
        public const string PackageGuidString = "a4ff042d-6f8c-45f7-ae4b-47a5f9114161";

        /// <summary>
        /// Initializes a new instance of the <see cref="ConvertMvc5ToCore3CommandPackage"/> class.
        /// </summary>
        public ConvertMvc5ToCore3CommandPackage()
        {
            // Inside this method you can place any initialization code that does not require
            // any Visual Studio service because at this point the package object is created but
            // not sited yet inside Visual Studio environment. The place to do all the other
            // initialization is the Initialize method.
        }

        #region Package Members

        /// <summary>
        /// Initialization of the package; this method is called right after the package is sited, so this is the place
        /// where you can put all the initialization code that rely on services provided by VisualStudio.
        /// </summary>
        /// <param name="cancellationToken">A cancellation token to monitor for initialization cancellation, which can occur when VS is shutting down.</param>
        /// <param name="progress">A provider for progress updates.</param>
        /// <returns>A task representing the async work of package initialization, or an already completed task if there is none. Do not return null from this method.</returns>
        protected override async Task InitializeAsync(CancellationToken cancellationToken, IProgress<ServiceProgressData> progress)
        {
            // When initialized asynchronously, the current thread may be a background thread at this point.
            // Do any initialization that requires the UI thread after switching to the UI thread.
            await this.JoinableTaskFactory.SwitchToMainThreadAsync(cancellationToken);
        }

        #endregion
    }
}

開發 VsPackages 最難處理的就是 .vsct (Vsct, Visual Studio Command Table) VS IDE 命令表描述檔案了，因為 VS 自身也不支援直接新增或編輯這個檔案，你只可以用 vsct.exe 從 .cto 檔案來建立 .vsct 檔，或透過 Perl 腳本來建立，我通常直接複製官方 ConvertCTCToVSCT.pl Perl 語言來建立，有時比較懶就直接拿上一次的範本直接拿來修改，前面我提到它就是個 XML 檔案，一般不是太複雜的套件 OzCode, Web Essentials 等套件，以目前 Convert ASP.NET MVC 5 to .NET Core 3 這個套件來說，我只需要一個 <Command> 與 <Symbols> 標籤即可！

比較重要的是，VS 的選單與按鈕都是 CommandID，它代表一個命令，這個命令會使用一個 Guid，來對應 CommandID，因為不管是 Button 或 ToolBar 都需要建立 Symbols。

接著 Commands 的 Package 名稱要與 GuidSymbols 相同，程式碼部分使用前面的，Guid 來建立 CommandID 物件，因為在建立 CommandID 物件時，需要這個 Guid，並且將 CommandID 放入 OleMenuCommand 裡，因為 VS 的選單都是 OleMenuCommand。

private ConvertMvc5ToCore3Command(AsyncPackage package, OleMenuCommandService commandService)
{
    this.package = package ?? throw new ArgumentNullException(nameof(package));
    commandService = commandService ?? throw new ArgumentNullException(nameof(commandService));

    var menuCommandID = new CommandID(CommandSet, CommandId);
    var menuItem = new OleMenuCommand(this.Execute, menuCommandID);
    menuItem.BeforeQueryStatus += MenuItem_BeforeQueryStatus;
    commandService.AddCommand(menuItem);
}

如上方程式碼，Execute 方法便是在這裡指定，當然從程式中可以看的出來方法名稱不一定要取名為 Execute，MenuItem_BeforeQueryStatus 事件則是當按下去的專案不是 Web 類型專案時，可以 Disable 掉目前的 Menu Item，CommandService 是 VS IDE 提供的服務，將自定義的 OleMenuCommand 新增到 VS 選單裡面。

ServiceCommand 其實 OleMenuCommandService 它是在 AsyncPackage.InnitalizeAsync() 方法內透過傳入的 AyncPackage 的 GetServiceAsync 建立的。

OleMenuCommandService commandService = await package.GetServiceAsync(typeof(IMenuCommandService)) as OleMenuCommandService;

前面 ConvrtMvc5ToCore3Command 的程式碼中，我們在產生一個 OleMenuCommand 時，我們不是傳入 Execute() 方法的參考，Execute() 方法的程式碼如下：

private async void Execute(object sender, EventArgs e)
{
    await ThreadHelper.JoinableTaskFactory.SwitchToMainThreadAsync();

    string title = "Convert ASP.NET MVC5 to ASP.NET Core 3";
    string message = "您想要將目前的 ASP.NET MVC5 的專案 Convert 成 .NET Core 3 類型的專案嗎？";

    var result = VsShellUtilities.ShowMessageBox(this.package, message, title, OLEMSGICON.OLEMSGICON_INFO, OLEMSGBUTTON.OLEMSGBUTTON_OKCANCEL, OLEMSGDEFBUTTON.OLEMSGDEFBUTTON_FIRST);

    if (result == 1)
    {
        try
        {
            Project activeProject = GetSelectedProject();
            await ConvertProjectAsync(activeProject);
        }
        catch (Exception ex)
        {
            VsShellUtilities.ShowMessageBox(this.package, ex.Message, title, OLEMSGICON.OLEMSGICON_INFO, OLEMSGBUTTON.OLEMSGBUTTON_OK, OLEMSGDEFBUTTON.OLEMSGDEFBUTTON_FIRST);
        }
    }
}

這段程式碼就是當你按滑鼠右鍵點選『Convert ASP.NET MVC5 to ASP.NET Core 3』時，所執行的內容，大家容易誤會的是 VsShellUtilities 類別了，不是在 .NET 裡顯示 MessageBox 都是 System.Windows.Forms/WPF 當然理論上是沒錯，單須交由 IDE 去執行 MessageBox。

第一行的 await ThreadHelper.JoinableTaskFactory.SwitchToMainThreadAsync(); 是 AsyncPackages 提供的非同步方法，前面提到從 VS 2017 開始支援擴充套件的延遲載入，所以套件也會支援非同步 Execute，所以當非同步執行時，若不希望影響到 IDE 的 Main Thread 導致整個 IDE 停住可呼叫這個方法，好比是 System.Windows.Forms 裡的 DoEvents();

所以如果你有撰寫過 VS 2015 之前的 Extensibility SDK 擴充套件的話部分寫法會有些不同，不過要全部解說完畢可能要下一篇文章了，哈哈。

待續...

Github 原始程式碼：https://github.com/wugelis/ConvertMVC5ToCore31



關於 Gelis：

資深 .NET 技術顧問

FB 社團 (軟體開發之路)：

https://www.facebook.com/groups/361804473860062/

FB 粉絲團 (Gelis 的程式設計訓練營)：

https://www.facebook.com/gelis.dev.learning/

我講授過的課程 SlideShare：

https://www.slideshare.net/GelisWu


以下是我經營的項目與內容：

(1). 企業內訓課程

(2). 專業顧問


企業內訓課程：

1. .NET Core 3.1 從入門到進階

先前實體課程連結

2. 跨平台的 Web API Framework 框架設計

先前實體課程連結

3. 決戰 OOAD 系列課程 - 使用 UML

先前實體課程連結

4. 單元測試 UnitTest 與 Moq 物件實務課程

先前實體課程連結

5. 快速開發系列 - C# Project Templates 範本設計

留言

張貼留言

這個網誌中的熱門文章

什麼是 gRPC ？

圖片
圖片取自： https://grpc.io/docs/guides/ gRPC 是什麼？能吃嗎？ 在安裝了 .NET Core 3.0 之後，眼尖的朋友應該會發現，在新增 ASP.NET Core 網頁類型專案裡，會看見一個 gRPC Service 類型的專案，其實它也不是什麼很新的東西，早在十多年前 Google 就使用這樣的 RPC 協定進行一些大量的可靠性微服務的存取，聽到這，難道現有的 Web API 不可靠嗎？其實不是的，它主要用在移動設備等提供高效簡單且跨平台的通訊與熱插拔的驗證機制。 gRPC 的運作原理 gRPC 顧名思義，是種基於 RPC 的通訊協定，不同於 Web API 走的傳統 HTTP 基礎協定，它有點像是 Socket ，但應該說是基於 Socket， 或精確地來說它是基於 HTTP/2 的協定 ，gRPC 是種協議緩衝協定，它必須事先定義 IDL (Interface Definition Language) 描述檔，看到 IDL 對於一些熟悉 COM／DCOM 的朋友一定非常的熟悉，對！沒錯！就是類似的東西！但，這邊的 IDL 是用一種副檔名為 .proto 檔案來是先定義在分散式環境中，要傳輸的序列化結構資訊，當然它也可以跟 JSON 一起使用。 也就是說，要使用 gRPC 您必須先定義 .proto 協議，然後透過 Compile 的支援，編譯成特定語言框架。而很高興的是，C# 也支援了，然而其實根據官方的資料顯示，C# 應該在 .NET Core 2.1 開始就支援了，只是到了 .NET Core 3.0 才有樣版的支援。 而使用 gRPC 的協議緩衝區的服務可以做到 Stub 的機制，也就是說，它就像是許多 RPC 一樣，Client 在呼叫 Server 端時，其實是對 Stub 進行叫用，Stub 在這就像個緩衝區一般，但更細部的說，應該是一個遠程服務的替身，這應該又讓許多熟悉 COM／RPC 通訊的朋友覺得熟悉了起來，是的！沒有錯。 在 .NET Core 3.0 裡使用 gRPC 目前支援 .proto 擴展為 gRPC 協議緩衝區的編譯器只有 .NET Core 了 ， 根據 Github 上的說明 .NET Framework 4.5+ 以上或 Mono 4+ 以上也可支援，而 gRPC 也完全的跨平台。要在 .
閱讀完整內容

什麼是 gRPC（二）- 來撰寫第一個 Hello World 吧！

圖片
前言 上一篇 什麼是 gRPC ，筆者大致介紹了 gRPC Service 的基本概念，這一次，我們就來小試一下身手，撰寫一個 Hello World （迷之音：嘗試新技術時，總是得先來一個 Hello World ～我不想違背這良好傳統阿阿阿阿） 使用環境 Visual Studio 2019 .NET Core 3.0.100-preview3-010431 開始進行 撰寫 gRPC 除了先準備好基礎環境、選定一種 作業系統／ 程式語言 Language 外、（Framework／SDK／Runtime）等環境備妥後，就可以開始撰寫， (1). 開始撰寫 gRPC 第一步就是先定義 .proto 協議了 上一篇筆者提到，gRPC 的 Server 與 Client 必須使用相同的協議才可進行溝通，一般來說，你應該使用 protoc.exe 編譯器先行編譯過 greet.proto 協議檔，並產出 C# 程式碼檔案後才可繼續，而在 Visual Studio 2019 裡，拜 MSBuild 之賜，已經有人預先寫好 .Target 檔案了 （什麼是 MSBuild ？什麼是附檔名 .Target 檔案可參考： MSBuild .targets 檔案 ） 筆者先撰寫一個 SayHelloWorld 方法如下： 在協議裡，除了在 service Class 撰寫要公開存取的方法外， 必須在提供『傳入訊息型態』、『回傳訊息型態』 ，這邊我先定義兩個 message，一個是『 HelloMyFirstgRPC 』、另一個是『 HelloMyReply 』 在撰寫 proto 協議檔時，建議先決定 message 回傳型態與傳入的型態，那麼 Visual Studio 2019 會有 InteillSense 的完整支援。不得不說 Visual Studio 2019 在 .proto 協議編輯上的支援已經算不錯了。 注意： 一般來說，Visual Studio 2019 會在背景裡自動編譯 .proto 協議檔案，但始有可能不會有任何提示，所以您也可以自行使用命令列工具進行手動編譯，如下圖，若編譯失敗會出現錯誤訊息，如下圖顯示 return 關鍵字錯誤： protoc.exe 編譯器 & 相關 MSBuild Tools 會隨著 NuGet 套件在 Vis
閱讀完整內容

常見的程式碼壞味道（Code Smell or Bad Smell）

圖片
常見的程式碼壞味道（Code Smell or Bad Smell） 圖片取自：https://www.slideshare.net/ElMahdiBenzekri/art-of-refactoring-code-smells-and-microservices-antipatterns 前言 究竟重複的程式碼要不要共用它？傳統的軟體開發上，重複的程式碼幾乎被視為罪惡的來源，但是它真的有多可怕？ 常見的 Code Smells The Dispensable （一些可有可無的） Lazy Class (冗員類別） 如果一個類很少使用它會增加代碼庫的複雜性，從而阻礙開發。這樣的類可能是不必要的，它的功能可以成為另一個類的一部分。 Data Class (只有資料的類別） 一個類別只有包含『資料』未包含Methods，也就是說並未包含行為，不具行為模式的類別代表該『實例』容易被【其他類別所操控】。 Duplicate Code (重複的程式碼) 如描述，這也是上次有分享在我的 FB 社團 軟體開發之路［德國資深架構師給新手的建議］ 中有產生非常熱烈討論，這在社團朋友提醒下想起 Refactor 重構一書裡曾提過 rule of three 法則， 這個法則的定義是這樣的，有時部分程式碼重複其實是允許的（不是說重複一定是是被允許的）而是在某些 Context 情境下，該程式碼有一段時間不會衍伸別的功能 或 需求一段時間不會異動、且如要將它 DRY 會產生的『複雜度』或『花費時間』遠高於預估的時間 或 不值得在目前這個專案的節骨眼上花費這個時間來做這件事，加上它 DRY 產生的複雜度偶後產生的維護成本【遠高於】不 DRY 的情況下的維護本，那麼，在這個時候，這個異動頻率【極低】的程式碼就不需要花費這個時間來 DRY 了！！ 因為重點在於，重構是需要『成本』的。(迷之音：DRY 是種抽象化阿~😎) 這讓我想起之前，大約在 2016 年左右，在 101 的樓上某金融業客戶，曾經做過一個專案，這個專案就是因為客戶 DMZ 環境的因素，我讓內網的 Webside 與 DMZ 的網站保留了部分重複的程式碼，因為這段程式碼終年不需要異動，我也懶得花這個時間，而我居然也忘了這記件事情了.. 哈哈 Orz 不過原歸正傳，我個人還是認為，其實適當
閱讀完整內容