Converting Driver Projects From Earlier Versions of Nimbus

1. Be sure to make a backup copy of your entire driver solution if it is not maintained in source control.

2. If the conversion fails at any point, the process must be started again using the original version. Attempting to close and re-open a partially-converted driver will produce unexpected results.

3. Delete the following items, as they easily become invalid between Visual Studio Versions, and they are automatically re-generated by Visual Studio upon opening a solution.

   • .vs folder

   • .VC.db file

Nimbus performs a number of required transforms to your driver solution in order to fully migrate it to the latest version. While this topic does not provide an exhaustive listing of all of these modifications, there are some that are helpful to be aware of, as they can influence how, and if, the project builds successfully immediately after conversion, or whether some manual conversion tasks are required.

1. IVI-COM and IVI.NET unit tests will get updated to target .NET Framework 4.5, if they are not already targeting at least that version. This is required by the MSTest framework used for these projects.

   To achieve this, Nimbus removes the existing unit test project reference to Microsoft.VisualStudio.QualityTools.UnitTestFramework and adds the requisite PackageReference entries for the MSTest framework.

2. Nimbus converts driver projects, unit test projects (C# and C++), help projects, and setup projects. No conversion is performed on console application projects in the solution, even if they were originally created using the Nimbus wizard.

3. All of the following projects will be converted to SDK-style projects:

   • IVI.NET driver projects

   • IVI.NET and IVI-COM unit test projects

   • IVI.NET, IVI-COM, and IVI-C help projects

   • IVI.NET, IVI-COM, and IVI-C setup projects

   One important (and useful) feature of SDK-style projects is that several of the common assembly attributes that would previously exist in the AssemblyInfo.cs file are managed as MSBuild project properties. This is a much more effective approach for managing important assembly-level metadata, such as the AssemblyVersion and the AssemblyFileVersion.

   As part of the conversion to SDK-style projects, Nimbus will remove the following assembly attributes from the AssemblyInfo.cs file:

   Note
   These assembly attribute modifications are only done for IVI.NET driver projects, IVI.NET unit test projects and IVI-COM unit test projects, since those are the three C# project types that are automatically converted to SDK-style.

   • AssemblyCompanyAttribute

   • AssemblyCopyrightAttribute

   • AssemblyDescriptionAttribute

   • AssemblyFileVersionAttribute

   • AssemblyProductAttribute

   • AssemblyTitleAttribute

   • AssemblyVersionAttribute

   For IVI.NET and IVI-COM unit tests, any of the above that appeared in the project's AssemblyInfo.cs file are injected directly into the project file.

   For IVI.NET driver projects, the values of some of these attributes is defined very precisely by the IVI specifications. Consequently, Nimbus maintains these values automatically in the Nimbus.Driver.IviNet.props file within the Nimbus Build Tools NuGet package.

   The following properties are defined in the IVI.NET .props file to provide the same functionality as the corresponding assembly attributes:

   • <FileVersion>

   • <Product>

   • <Title>

   • <Version>

   Important

   With regards to the above four assembly attributes, any values discovered in the AssemblyInfo.cs file are ignored. Because IVI prescribes these values precisely, Nimbus is able to compute and maintain these values automatically in the Nimbus.Driver.IviNet.props file. This could result in a change in the values compiled into the resulting driver assembly, relative to what was compiled into the assembly prior to conversion. However, any difference would be the result of the driver having been manually modified after initial generation to use a non-compliant value.

   For IVI.NET drivers, if any of the following appeared in the AssemblyInfo.cs file, then their values are injected directly into the corresponding MSBuild properties in the driver project file.

   • AssemblyCompanyAttribute

   • AssemblyCopyrightAttribute

   • AssemblyDescriptionAttribute

4. Nimbus injects MSBuild properties into the driver, help, setup, and C# unit test projects to unify the intermediate and output path locations under a single build folder. This greatly simplifies management of build artifacts, installer build operations, and facilitates better incremental build behavior.

   To achieve this, Nimbus removes all of the following MSBuild properties from the driver, help, setup, and C# unit test projects:

   • <BaseIntermediateOutputPath>

     <BaseOutputPath>

     <IntDir>

     <IntermediateOutputPath>

     <OutDir>

     <OutputPath>

     <TargetBaseName>

     <TargetName>

   Important

   Nimbus only performs the output and intermediate folder unification for driver, help, setup, and C# unit test projects. It specifically does NOT, due to Visual Studio limitations, perform automatic output folder transformation for IVI-C wrapper unit test projects or any of the C#, Visual Basic, or C# console application projects. See the section below on manual conversion tasks for details on the simple changes to unify the output of these projects as well.

5. The Nimbus Build Tools are now used directly by end users building installed drivers. As such, the build tools no longer ship with Nimbus-created drivers. The Nimbus conversion process removes NTL from IVI-COM setup projects, NCL from IVI.NET setup projects, and NRT from IVI-C setup projects.

   Additionally, because there are no build tools included with the IVI.NET driver installer, the Nimbus migration process removes NimbusExpressEULA page that would appear as part of IVI.NET driver installation.

To convert your driver to Nimbus 5:

1. After conversion, the obj folder will likely appear in Solution Explorer as a member of some projects. This folder can safely be deleted from Solution Explorer, and from disk.

2. For native IVI-C unit tests, Visual Studio 2019 pre-defines the template specialization for ViInt64 This specialization is not defined in earlier versions of Visual Studio, so Nimbus generated it automatically. A build error occurs if this redundant definition remains in the native IVI-C unit tests for Visual Studio 2019. Simply delete the following template specialization at the top of the IVI-C unit test.

   C++

   Copy

   template<> static std::wstring ToString<ViInt64>(const ViInt64& t) { RETURN_WIDE_STRING(t); }

3. Nimbus converts help projects to SDK-style projets. The large number of items that were previously managed directly in each help .nhproj file are now managed with file globs defined in the Nimbus.Help.targets file within the Nimbus Build Tools.

   XML

   Copy

   <!-- These file globs define the items included in the project. -->
   <ItemGroup>
     <Content Include="Template\**\*.js" />
     <Content Include="Template\**\*.html" />
     <Content Include="Template\**\*.htm" />
     <Content Include="Template\**\*.jpg" />
     <Content Include="Template\**\*.gif" />
     <Content Include="Template\**\*.png" />
     <Content Include="Template\**\*.css" />
     <Content Include="Template\Manifest.xml" />
   </ItemGroup>

   If you added items to your help project folder that are included in your help project content, then ensure they are included in the list of file extensions above. If not, simply add the appropriate glob for your file extension directly to your .nhproj file.

   Conversely, if the file globs above would include content that you explicitly wish to be exluded, then a file glob can be added to the project file with an Exclude attribute. Please consult the Microsoft online documentation for details in the syntax of file globs.

4. Nimbus automatically unifies the output of driver, help, setup, and C# unit test projects. IVI-COM C# and Visual Basic console applications are not automatically updated by the conversion process.

   To update IVI-COM C# and Visual Basic console applications to use the unified output folder:

   1. Use the $(OutputPath) in the <HintPath> element associated with the driver project reference.

      Important
      Without properly adjusting the <HintPath> element, the driver reference will not resolve and the console application project will not build.

   2. Paste the following code in the project file just above the <Import> element for Microsoft.Common.props.

      XML

      Copy

      <PropertyGroup>
        <BaseOutputPath Condition=" '$(BaseOutputPath)' == '' ">..\build\</BaseOutputPath>
        <BaseIntermediateOutputPath Condition=" '$(BaseIntermediateOutputPath)' == '' ">$(BaseOutputPath)obj\$(MSBuildProjectName)\</BaseIntermediateOutputPath>
        <OutputPath>$(BaseOutputPath)$(Configuration)\$(Platform)\</OutputPath>
        <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
        <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
      </PropertyGroup>

5. Nimbus automatically unifies the output of driver, help, setup, and C# unit test projects. IVI-COM C++ console applications and IVI-C wrapper C++/CLI unit tests are not automatically updated by the conversion process.

   To update IVI-COM C++ console applications and IVI-C wrapper C++/CLI unit tests to use the unified output folder:

   1. Paste the following code in the project file just below the <Import> element for Microsoft.Cpp.props.

      XML

      Copy

      <PropertyGroup>
        <NormalizedPlatform Condition=" '$(Platform)' == 'x86' OR '$(Platform)' == 'Win32' OR '$(Platform)' == 'AnyCPU' ">x86</NormalizedPlatform>
        <NormalizedPlatform Condition=" '$(Platform)' == 'x64' ">$(Platform)</NormalizedPlatform>
        <OutDir>..\build\$(Configuration)\$(NormalizedPlatform)\</OutDir>
        <IntDir>..\build\obj\$(MSBuildProjectName)\$(Configuration)\$(NormalizedPlatform)\</IntDir>
      </PropertyGroup>

   2. For the IVI-C wrapper unit test only, change the <DriverId> element to <DriverName> and change the value to match that of the driver name.

   3. Remove any <OutDir> and <IntDir> elements.

   4. Add the $(OutputPath) to each <AdditionalLibraryDirectories> element.