Skip to main content

Distribution using package function

Extensions can be distributed using the package function in addition to direct binary distribution. By using the package function, content such as extensions and samples can be version-controlled and easily used by other users. Packages can be distributed at Next Design Extensions.

Packaging and its benefits​

Packaging means creating Next Design extensions in a file format that can be distributed. It makes distributing and updating extensions very simple. The main benefits are:

  • Easy to install and update
    • You can now install, uninstall, and update extensions with one click.
    • Users can be notified on the Next Design screen when a new version is published.
  • Easy version control
    • Easy version control as multiple versions of the extension can be distributed.
    • You can view the package overview and changes by version on the Next Design screen.
    • You can develop extensions to work with specific versions of Next Design.
  • Can be distributed without the need for a dedicated server
    • Since you can register your own package deployment folder, it is possible to easily distribute using a network folder or version control tools such as GitHub/GitLab or Subversion.
  • You can distribute profiles and samples
    • You can distribute not only extensions but also profile and project templates.

Context​

Prepare the tools and environment required for packaging. Skip this if you have already installed it.

  1. Install NDExt.

    NDExt is a command line tool that supports extension development. You can install it by simply running the following from a command prompt: To run this program, you need to install .NET 6.0 SDK.

    dotnet tool install --global NDExt

  2. Create an extension project using project template in Visual Studio.

    Execute the following command from the command prompt to register it as a Visual Studio template.

    dotnet new --install NextDesign.Extension.ProjectTemplates

Create a package​

There are several ways to package Next Design extensions, but the simplest is using Visual Studio and the command line tool NDExt. This section explains how to configure using Visual Studio in the following order.

  1. Create an extension project in Visual Studio.

  2. Set the package information in the Visual Studio project settings dialog.

    In the case of Visual Studio 2022, the dialog looks like the following.

    A description of each property is as follows.

    Setting itemsDescription
    Package IDA unique name that distinguishes the package. For example, "MyCompany.SomePackage". Please use only letters, . and numbers. This corresponds to ① in the figure below.
    Package versionUsed as the version to identify the package. It will be something like “1.0.0”. This corresponds to ③ in the figure below.
    CreatorInformation about the package creator. Please enter your company name etc.
    DescriptionUsed for the package title and description. It can be any string. Only the first line is used for the package title, while the full text is used for the package description. This corresponds to ② and ⑤ in the figure below.
    Project URLURL of the site related to the package. This corresponds to ④ in the figure below.

    The [Packages] dialog displays as follows.

Caution
  • Make sure the package ID is unique across all packages. Also, please do not use Japanese names as they will result in an error.
  • The description property is used as the package title and package description.
  • If you want to publish a new version, please update the package version. If it was created with "1.0.0", update it to a larger number like "1.0.1".
  • If the version number format is not x.x.x (x is any number), you cannot disable it from Next Design after installation.

Build the package​

Use NDExt to build the package. When you run the following command on the command line, it searches for all extension projects (csproj) under the execution directory, builds them, and packages them.

C:\MyProjects\NdExt1\NdExt1> ndext pack
  • If the ndext pack command is successfully executed, a nupkg file will be created in the output folder called ndpackages. This file is the package file.
  • The package file has the format {PackageId}.{Version}.nupkg, such as NdExt1.1.0.0.nupkg.
  • The contents of nupkg are zip files. This zip file contains the package definition file (nuspec file) and extension and profile files.

When you open the nupkg file with NuGet Package Explorer, which is a tool that allows you to view and edit nupkg files, it looks like the following.

  • The number under the extensions folder is the corresponding Next Design version. The extension binaries to be distributed will be placed in that subfolder.
  • The samples folder and templates folder are used to register Next Design samples and template functions. When you create a project file with NDExt new, the samples folder and templates folder are created in the pkgContents folder, so place the Next Design project file and template file under them. When you build a package with ndext pack, it is automatically registered in the package.
Caution
  • Please close Next Design when building. Packaging may fail when Next Design is running.
  • If you include Japanese file names in the package configuration file, such as sample or template files or documents, the package will fail, so please use English file names.

Publishing the package​

From the [Setting] button of Next Design Extensions, add package source and install this nupkg file. You can publish it by placing . A package source is a directory or a web server (website) called a NuGet server. Here we will explain publishing using a folder as the package source as the simplest method.

  1. Add package sources.

    • Click File menu > Packages to open the Packages dialog.

    • Click the [Setting] button to display the [Extension Settings] dialog, and then press the [Add] button.

    • Specify the folder to distribute the package. This can be a network or local folder.

  2. Copy the package to your package source.

Copy the built nupkg file to the package source folder.

  1. Have each user extract the package source information and install it as an extension.

Now you can publish the package as Next Design Extensions.

Hint

The following methods are possible for deployment using the package source folder.

  • Share in a network folder that users can access
    • This is the simplest way to share only within your company or organization. Please set the network folder containing .nupkg as the package source.
  • Share folders on OneDrive, GoogleDrive, etc.
    • This is a method to share with external networks in the cloud. Create a folder containing .nupkg on your cloud drive and share it with multiple users. Each person sets their local drive as the package source.
  • Publish using GitHub/GitLab or Subversion
    • This is an effective method if you are familiar with Git and want to easily publish extensions to multiple users across organizations and networks. Register a local working folder such as GitHub or Subversion as a package source.
    • Updated with the latest configuration management features. To publish a new package to your users, you will need to have your repository up to date, but no special environment is required for publishing.

Package update​

To update a package, update the version number and create the package. A package source folder can store multiple versions of the same package ID.

  1. Change the package version in the project settings to the new version. For example, for "1.1.0", change it to "1.2.0".
  2. Build the package.
  3. Assume that the .nupkg file you created looks like MyExtA.1.2.0.nupkg. Place this file in your package source folder.

For example, if the file structure in the package source folder is as follows, there are packages MyExtA and MyExtB, and two versions of each are published.

packageSource\
  MyExtA.1.0.0.nupkg
  MyExtA.1.2.0.nupkg
  MyExtB.2.0.0.nupkg
  MyExtB.2.1.0.nupkg

  1. When a new version is published, you will see a notification icon on the Next Design status bar to let you know that there are packages available for update.

  2. Click the icon to display the [Packages] dialog. You can check which packages have updates, so you can update them by pressing the [Update] button.

Advanced topics​

This section describes advanced topics related to package distribution.

Register the project to be displayed on the start page​

By placing Next Design project files for samples and templates in the pkgContents folder of the Visual Studio project you created, you can display them on the Next Design start page.

  1. Register the sample and template projects to be displayed on the start page in the pkgContents folder.

note
  • No need to set copy to output directory in file properties.
  • Both samples and templates create new copies of the project files. Although there is no major difference in behavior, we recommend distributing profiles in template format.

Make your package international​

You can set multiple languages ​​for Title and Description as shown below. Automatically selects the appropriate language to display on the UI according to the current UI display language.

  1. Enter your international packaging information.

    In the project settings, enter text for Japanese and English, such as { "ja" : "Japanese description" , "en" : "english here"} . Only the first line is used for the title, while the entire text is used for the description.

  2. The package display text will now change depending on the Next Design display language.

  3. If you check with NuGet Package Explorer, the Description is as follows.

Specify the version of Next Design to run​

To specify the version of Next Design, use the -v argument when building the package to specify the version of Next Design to run. It will work with this version or higher.

C:\MyProjects\NdExt1\NdExt1> ndext pack -v 2.5

The build result should look like this:

Prepare your own package publishing server​

Next Design's package server is compliant with the NuGet V2/V3 protocol. To release a server that can only be accessed by a limited number of users, such as an organization, you need to prepare your own NuGet server. For more information, see Microsoft's Host your own NuGet feeds(https://docs.microsoft.com/en-us/nuget/hosting-packages/overview).

Folder structure within the package​

If you want it to work with all app versions, set the number directly under extensions to 2.0.

.\extensions\
  2.0\
    NdExt1\
        sampleExtension.dll
        markdig.dll

To accommodate multiple Next Design versions:

.\extensions\
  2.0\
    NdExt1\
      sampleExtension.dll
      markdig.dll
      manifest.json
  2.5\
    NdExt1\
      sampleExtension.dll
      markdig.dll
      manifest.json

If you want to place multiple extensions, do the following:

.\extensions\
  2.0\
    NdExt1\
      images\
        xx.png
      ext1.dll
      manifest.json
    NdExt2\
      images\
        xx.png
      ext2.dll
      manifest.json
  
.\samples\
  2.0\
    aaa.nproj

.\templates\
  2.5\
    aaa.nprot
    bbb.nprot

How to create packages using other tools​

Next Design packages are powered by NuGet. Therefore, in addition to using Visual Studio and NDExt, there are the following methods.

  • Directly create a nuspec file and package it with the dotnet pack command
  • Create using Nuget Package Explorer
Last updated on