Създаваме един проект за плъгин с компилация за различни версии на Revit/AutoCAD

При разработката на плъгини за CAD приложения (в моя случай това е AutoCAD, Revit и Renga) с времето се появява един проблем – излизат нови версии на програмите, променя се тяхното API и е необходимо да се направят нови версии на плъгините.

Когато имате само един плъгин или все още сте новичок самоук в това, можете просто да направите копие на проекта, да промените нужните места в него и да съберете новата версия на плъгина. Съответно, последващото въвеждане на промени в кода ще доведе до многократно увеличаване на трудозатратите.

С натрупването на опит и знания ще намерите няколко начина за автоматизация на този процес. Аз преминах през този път и искам да ви разкажа до какво стигнах в крайна сметка и колко удобно е.

Първо, нека разгледаме начина, който е очевиден и с който дълго време ползвах.

Връзки към файловете на проекта

И за да е всичко просто, нагледно и понятно, ще опиша всичко на абстрактен пример за разработка на плъгин.

Отваряме Visual Studio (аз имам версия Community 2019. И да – на руски език) и създаваме ново решение. Нека го наречем MySuperPluginForRevit

Ще направим плъгин за Revit за версии 2015-2020. Затова ще създам нов проект в решението (Библиотека на класове Net Framework) и ще го наречем MySuperPluginForRevit_2015

Трябва да добавим връзки към API на Revit. Разбира се, можем да добавим връзки към локални файлове (това ще изисква инсталиране на всички необходими SDK или версии на Revit), но ще поемем по правилния път и ще свържем NuGet пакета. Можете да намерите доста пакети, но аз ще използвам своите собствени.

След свързването на пакета, щракваме с десния бутон на мишката върху елемента «Връзки» и избираме от менюто опцията «Премести packages.config в PackageReference…»

Ако в този момент започнете да се паникьосвате, защото в прозореца с свойства на пакета липсва важната опция «Копиране локално», която задължително трябва да зададем на стойност false, не се паникьосвайте – отидете в папката с проекта, отворете файла с разширение .csproj в удобен за вас редактор (аз използвам Notepad++) и намерете записа за нашия пакет. В момента изглежда така:

1.0.0

Добавяме му свойството runtime. Ще се получи така:

1.0.0
  runtime

Сега, при изграждане на проекта, файловете от пакета няма да бъдат копирани в изходната папка.
Продължаваме напред – веднага да представим, че нашият плъгин ще използва нещо от Revit API, което се е променяло с времето, с излизането на нови версии. Или просто ни е нужно да променим нещо в кода в зависимост от версията на Revit, за която правим плъгина. За решаване на такива различия в кода ще използваме символи на условна компилация. Ще отворим свойствата на проекта, ще премини на раздела „Сглобяване“ и в полето „Идентификатори на условна компилация“ ще напишем R2015.

Обърнете внимание, че символът трябва да се добави и за конфигурацията Debug, и за конфигурацията Release.

Докато сме в прозорците със свойства, веднага преминаваме на раздела „Приложение“ и в полето „Предметно пространство по подразбиране“ и премахваме суфикса _2015, за да имаме универсално и независимо от името на сборката пространство:

В моя случай, в крайния продукт плъгините на всички версии се съхраняват в една папка, затова името на сборките ми остава със суфикс от вида _20хх. Но можете да премахнете суфикса и от името на сборката, ако се предполага разположение на файловете в различни папки.

Преминаваме към кода на файла Class1.cs и имитираме там определен код с оглед на различните версии на Revit:

namespace MySuperPluginForRevit
{
    using Autodesk.Revit.Attributes;
    using Autodesk.Revit.DB;
    using Autodesk.Revit.UI;

    [Regeneration(RegenerationOption.Manual)]
    [Transaction(TransactionMode.Manual)]
    public class Class1 : IExternalCommand
    {
        public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
        {
#if R2015
            TaskDialog.Show("ModPlus", "Здравей, Revit 2015");
#elif R2016
            TaskDialog.Show("ModPlus", "Здравей, Revit 2016");
#elif R2017
            TaskDialog.Show("ModPlus", "Здравей, Revit 2017");
#elif R2018
            TaskDialog.Show("ModPlus", "Здравей, Revit 2018");
#elif R2019
            TaskDialog.Show("ModPlus", "Здравей, Revit 2019");
#elif R2020
            TaskDialog.Show("ModPlus", "Здравей, Revit 2020");
#endif
            return Result.Succeeded;
        }
    }
}

Веднага взех предвид всички версии на Revit над 2015 година (които бяха налични по времето на писането на статията) и веднага отразих наличието на символи за условна компилация, които аз създавам по един и същ шаблон.

Преминаваме към главната изненада. Създаваме нов проект в нашето решение, само че вече за версията на плъгина за Revit 2016. Повтаряме всички описани по-горе действия, съответно заменяйки числото 2015 с числото 2016. Но файлът Class1.cs от новия проект изтриваме.

Файл с нужния код - Class1.cs - вече го имаме и просто трябва да поставим връзка в новия проект. Има два начина за поставяне на връзки:

1. Дълъг - натискаме с десния бутон на мишката върху проекта, избираме опцията „Добави“ -> „Съществуващ елемент“, в появилото се прозорче намираме необходимия файл и вместо опцията „Добави“ избираме опцията „Добави като връзка»

1. Кратък - директно в прозореца на решенията избираме необходимия файл (или дори файлове. Може дори цели папки) и ги плъзгаме в новия проект с натиснат клавиш Alt. Докато плъзгате, ще видите, че курсорът на мишката ще се променя от плюсче на стрелка, когато натиснете клавиша Alt.
   UPD: Добавих малко объркване в този параграф - за да премествате няколко файла, трябва да натиснете Shift+Alt!

След приключването на процедурата, в нашия втори проект ще се появи файл Class1.cs с подходяща икона (синя стрелка):

По време на редактиране на кода в редактора, можете също да избирате в контекста на кой проект да се показва кодът, което ще ви позволи да виждате и редактирате кода при различни символи на условна компилация:

По тази схема създаваме всички останали проекти (2017-2020). Лайфхак – ако премествате файлове в изследователя на решения, не от основния проект, а от проекта, където вече са добавени като връзка, можете да не натискате клавиша Alt!

Описаният вариант е напълно добър до момента, в който добавите нова версия на плугина или нови файлове в проекта – всичко това става много досадно. Наскоро изведнъж осъзнах как да управлявам всичко това с един проект и преминаваме към втория метод.

Магия на конфигурациите

Ако сте прочели до тук, може да се възкликнете: «А защо описваше първия метод, ако статията веднага е за втория?!». Написах всичко, за да стане по-ясно защо ни трябват символи за условна компилация и в кои места проектите ни се различават. И сега разбираме по-добре какви точно различия в проектите трябва да реализираме, оставяйки само един проект.

И за да е всичко по-очевидно, няма да създадем нов проект, а ще направим промени в текущия ни проект, създаден по първия начин.

И така, първо премахваме всички проекти от решението, освен основния (съдържащ файловете). Т.е. проектите за версиите 2016-2020. Отваряме папката с решението и там изтриваме папките на тези проекти.

В решението ни остана един проект — MySuperPluginForRevit_2015. Отваряме неговите свойства и:

1. На вкладката „Приложение“ премахваме суфиксa от името на сборката _2015 (по-късно ще стане ясно защо)
2. На вкладката „Сглобяване“ премахваме символа на условната компилация R2015 от съответното поле

Забележка: в последната версия на Visual Studio има бъг – символите на условната компилация не се показват в прозореца със свойства на проекта, въпреки че те съществуват. Ако при вас се наблюдава този бъг, ще трябва да ги изтриете ръчно от файла .csproj. Въпреки това, все пак трябва да работим с него, така че продължаваме да четем.

Преименуваме проекта в прозореца на решението, като премахнем суфикса _2015 и след това изтриваме проекта от решението. Това е необходимо за поддържане на реда и чувството на перфекционизъм! Отваряме папката на нашето решение, преименуваме там по същия начин папката на проекта и зареждаме проекта обратно в решението.

Отваряме диспетчера на конфигурациите. Нуждаем се от конфигурация Release в принципе няма да е необходима, затова я изтриваме. Създаваме нови конфигурации с вече познатите имена R2015, R2016, …, R2020. Обърнете внимание, че не е необходимо да копирате параметри от други конфигурации и не трябва да създавате конфигурации на проекта:

Отиваме в папката с проекта и отваряме файла с разширение .csproj в удобен за вас редактор. Между другото, може да се отвори и в Visual Studio – трябва да експортирате проекта и след това в контекстното меню ще има необходимата опция:

Редактирането в Visual Studio е още по-предпочитано, тъй като редакторът подравнява и предлага подсказки.

В файла ще видим елементите PropertyGroup – в самия връх е общият, а следват елементите с условия. Тези елементи задават свойствата на проекта при неговото изграждане. Първият елемент, който е без условия, задава общите свойства, а елементите с условия съответно променят някои свойства в зависимост от конфигурациите.

Преминаваме към общия (първи) елемент PropertyGroup и гледаме свойството AssemblyName – това е името на сборката и то трябва да бъде без суфикс _2015. Ако има суфикс, изтриваме го.

Намираме елемента с условие

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">

Той не ни е нужен – изтриваме го.

Елемент с условие

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">

нужен за работа по време на етапа на разработка и отстраняване на грешки в кода. Можете да променяте свойствата му според вашите нужди – да задавате различни изходни пътеки, да променяте символите за условна компилация и т.н.

Сега създаваме нови елементи PropertyGroup за нашите конфигурации. В тези елементи е нужно да зададем само четири свойства:

• OutputPath – изходна папка. Аз задавам стандартната стойност binR20xx
• DefineConstants – символи за условна компилация. Трябва да зададете стойността TRACE;R20хх
• TargetFrameworkVersion – версия на платформата. За различни версии на Revit API е необходимо да зададете различни платформи.
• AssemblyName – име на сборката (т.е. името на файла). Можете да напишете точно нужното име на сборката, но за универсалност препоръчвам да зададете стойността $(AssemblyName)_20хх. Заради това предварително премахнахме суфиксa от името на сборката

Основното предимство на всички тези елементи е, че могат да бъдат просто копирани в други проекти, без никакви промени. В статията по-долу ще приложа цялото съдържание на файла .csproj.

Добре, разбрахме свойствата на проекта – не е сложно. Но какво да правим с включените библиотеки (NuGet пакети). Ако погледнем по-нататък, ще видим, че включените библиотеки се задават в елементите ItemGroup. Но тук е проблемът – този елемент неправилно обработва условията, като елемент PropertyGroup. Може би дори е бъг на Visual Studio, но ако зададем няколко елемента ItemGroup с условия на конфигурации, а вътре поставим различни връзки към NuGet пакети, то при смяна на конфигурацията към проекта се свързват всички посочени пакети.

На помощ ни идва елементът Изберете, който работи според познатата ни логика if-then-else.

Използвайки елемента Изберете, задаваме различни NuGet пакети за различни конфигурации:

Цялото съдържание csproj

Debug
    AnyCPU
    {5AD738D6-4122-4E76-B865-BE7CE0F6B3EB}
    Library
    Properties
    MySuperPluginForRevit
    MySuperPluginForRevit
    v4.5
    512
    true
  
  
    true
    full
    false
    binDebug
    DEBUG;R2015
    prompt
    4
  
  
    binR2015
    TRACE;R2015
    v4.5
    $(AssemblyName)_2015
  
  
    binR2016
    TRACE;R2016
    v4.5
    $(AssemblyName)_2016
  
  
    binR2017
    TRACE;R2017
    v4.5.2
    $(AssemblyName)_2017
  
  
    binR2018
    TRACE;R2018
    v4.5.2
    $(AssemblyName)_2018
  
  
    binR2019
    TRACE;R2019
    v4.7
    $(AssemblyName)_2019
  
  
    binR2020
    TRACE;R2020
    v4.7
    $(AssemblyName)_2020
  
  
    
    
    
    
    
    
    
    
  
  
    
    
  
  
    
      
        
          1.0.0
          runtime
        
      
    
    
      
        
          1.0.0
          runtime
        
      
    
    
      
        
          1.0.0
          runtime
        
      
    
    
      
        
          1.0.0
          runtime
        
      
    
    
      
        
          1.0.0
          runtime
        
      
    
    
      
        
          1.0.0
          runtime

Обърнете внимание, че в едно от условията съм посочил две конфигурации чрез ИЛИ (Or). По този начин ще се свърже необходимият пакет при конфигурация Debug.

И ето, че почти всичко е перфектно. Зареждаме отново проекта, включваме необходимата конфигурация, извикваме в контекстното меню на решението (не на проекта) опцията «Възстановяване на всички пакети NuGet» и виждаме как се променят пакетите.

И ето, на този етап стигнах до задънена улица – за да съберем всички конфигурации, можехме да се възползваме от пакетното изграждане (меню «Сглобяване“ -> „Пакетно изграждане»), но при превключване на конфигурации не става автоматично възстановяване на пакетите. И при сглобяването на проекта също не се случва, въпреки че, по идея, трябва. Не намерих решения на този проблем с стандартни средства. Вероятно това е също баг в Visual Studio.

Затова за пакетно изграждане беше решено да се използва специална система за автоматизирано изграждане Nuke. В действителност не исках това, тъй като счита, че е излишно в рамките на разработката на плъгини, но в момента не виждам друга опция. А на въпроса «Защо именно Nuke?» отговорът е прост – използваме го на работа.

И така, преминаваме в папката на нашето решение (не на проекта), задръжте клавиша Shift и кликнете с дясната мишка на празно място в папката – в контекстното меню изберете опцията «Отворете PowerShell прозорец тук».

Ако нямате инсталиран nuke, първо напишете командата

dotnet tool install Nuke.GlobalTool –global

Сега напишете командата nuke и ще ви бъде предложено да конфигурирате nuke за текущия проект. Не знам как да го напиша по-добре на руски – на английски ще бъде написано Could not find .nuke file. Do you want to setup a build? [y/n]

Натискаме клавиша Y и след това ще видим непосредствените опции за конфигуриране. Нуждаем се от най-простия вариант с използване на MSBuild, затова отговаряме както на екрана:

Превключваме на Visual Studio, която ще ни предложи да презаредим решението, тъй като е добавен нов проект. Презареждаме решението и виждаме, че имаме нов проект build в който ни интересува само един файл – Build.cs

Отваряме този файл и пишем скрипт за изграждане на проекта за всички конфигурации. Или използваме моя скрипт, който можете да редактирате според вашите нужди:

using System.IO;
using Nuke.Common;
using Nuke.Common.Execution;
using Nuke.Common.ProjectModel;
using Nuke.Common.Tools.MSBuild;
using static Nuke.Common.Tools.MSBuild.MSBuildTasks;

[CheckBuildProjectConfigurations]
[UnsetVisualStudioEnvironmentVariables]
class Build : NukeBuild
{
    public static int Main () => Execute(x => x.Compile);

    [Solution] readonly Solution Solution;

    // Ако името на решението и името на проекта (плъгин) са различни, посочете името на проекта (плъгин) тук
    string PluginName => Solution.Name;

    Target Compile => _ => _
        .Executes(() =>
        {
            var project = Solution.GetProject(PluginName);
            if (project == null)
                throw new FileNotFoundException("Не е намерен!");

            var build = new List();
            foreach (var (_, c) in project.Configurations)
            {
                var configuration = c.Split("|")[0];

                if (configuration == "Debug" || build.Contains(configuration))
                    continue;

                Logger.Normal($"Конфигурация: {configuration}");

                build.Add(configuration);

                MSBuild(_ => _
                    .SetProjectFile(project.Path)
                    .SetConfiguration(configuration)
                    .SetTargets("Restore"));
                MSBuild(_ => _
                    .SetProjectFile(project.Path)
                    .SetConfiguration(configuration)
                    .SetTargets("Rebuild"));
            }
        });
}

Връщаме се в прозореца на PowerShell и отново пишем командата nuke (може да се пише командата nuke с указание на необходимите Цел. Но ние имаме един Цел, който се стартира по подразбиране). След натискане на клавиша Enter ще се почувстваме истински хакери, тъй като в киното ще се извърши автоматичното сглобяване на нашия проект за различни конфигурации.

Между другото, можете да използвате PowerShell директно от Visual Studio (меню «Изглед“ -> „Други прозорци“ -> „Конзола на пакета»), но там всичко ще бъде черно-бяло, което не е много удобно.

С това моята статия приключва. Уверен съм, че с варианта за AutoCAD ще можете да се справите сами. Надявам се, че представеният тук материал ще намери своите «клиенти».

Благодаря за вниманието!

Източник: habr.com