Skip to main content

Distribution by package function

Extensions can be distributed by the package function in addition to the direct distribution by binary. By using the package function, it becomes easy for other users to manage the version of contents such as extensions and samples. Packages can be distributed at Next Design Extensions.

Packaging and its benefits

Packaging is the creation of Next Design extensions in a file format that can be distributed. Distributing and updating extensions will be much simpler. The main merits are as follows.

  • Easy to install and update
    • You will be able to install, uninstall and update extensions with just one click.
    • You can notify users on the Next Design screen when a new version is released.
  • Easy version control
    • Version control is easy because multiple versions of extensions can be distributed.
    • You can view the package summary and version-specific changes on the Next Design screen.
    • You can develop extensions that work with a particular version of Next Design.
  • Can be distributed without the need for a dedicated server
    • Since you can register your own package expansion folder, you can easily distribute it using a network folder or a version control tool such as his GitHub / GitLab, Subversion.
  • Profiles and samples can be distributed
    • Not limited to extensions, you can distribute profiles and project templates.

Premise

Prepare the tools and environment required for packaging. If you have already installed it, skip it.

  1. Select Install NDExt.

    NDExt is a command line tool that helps you develop extensions. You can install it by simply executing the following from the command prompt. To run this program, you need to install .NET Core 3.1 SDK.

    dotnet tool install --global NDExt

  2. In Visual Studio, use Project Templates to create an extension project.

    If you execute the following command from the command prompt, it will be registered as a template of Visual Studio.

    dotnet new --install NextDesign.Extension.ProjectTemplates

Creating a package

There are several ways to create a package for the Next Design extension, but the simplest is to use Visual Studio and the command line tool NDExt. Here, the setting method using Visual Studio is explained in the following order.

  1. In Visual Studio, select Create Extension Project.

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

    In the case of Visual Studio 2022, the dialog is as follows. Visual Studio 2019 has a different UI but the same properties.

    The description of each property is as follows.

    Setting itemsDescription
    Package IDA unique name that distinguishes the package. Specify something like "MyCompany.SomePackage". Use only alphabets and . and numbers. It corresponds to β‘  in the figure below.
    Package versionUsed as a version to identify the package. For example, β€œ1.0.0”. It corresponds to β‘’ in the figure below.
    DescriptionUsed for the title and description of the package. It can be any character string. Only the first line is used for the package title, while the full text is used for the package description. It corresponds to β‘‘ and β‘€ in the figure below.
    AuthorInformation about the creator of the package. Please enter the company name etc.
    Project URLThe URL of the site about packages. It corresponds to β‘£ in the figure below.

    In the [Manage Extensions] dialog, you should see something like this:

Attention
  • Make sure the package ID is unique for all packages. Also, do not use Japanese names as they will cause an error.
  • The description property is used as the title of the package and the description of the package.
  • Please update package version if you want to publish a new version. If you created it with "1.0.0", update it with a larger number such as "1.0.1".
  • If the version number format is not x.x.x (x is any number), it cannot be disabled from Next Design after installation.

Package build

Use NDExt to build the package. Run the following command on the command line to find the project (csproj) for all extensions under the run directory, build and package it.

C:\MyProjects\NdExt1\NdExt1> ndext pack
  • Successful execution of the ndext pack command will create a nupkg file in the output folder ndpackages. This file is the package file.
  • The package file is in 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 the extension and profile files.

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

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

Publishing the package

From the Next Design Extensions button, select Package Source. You can publish it by adding it and placing this nupkg file. A package source is a directory or a web server (website) called a NuGet server. Here, we will explain how to publish using a folder as the package source as the easiest method.

  1. Add the package source.

    • Click File menu> Manage Extensions to open the Manage Extensions dialog.

    • Click the [Settings] button to display the [Extension Settings] dialog, and click the [Add] button.

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

  1. Copy the package to the package source.

    Copy the built nupkg file to the package source folder.

  2. Ask each user to expand the package source information and install it as an extension.

You can now publish your package as Next Design Extensions.

Tips

The following methods can be considered for extraction using the package source folder.

  • Share in a user-accessible network folder
    • The simplest way to share only within your company or organization. Set the network folder containing .nupkg as the package source.
  • Share folders on OneDrive, Google Drive, etc.
    • This is a method of sharing with an external network in the cloud. Create a folder containing .nupkg on the cloud drive and share it with multiple users. Each person sets the local drive as the package source.
  • Publish using GitHub / GitLab or Subversion
    • Familiar with Git etc., it is an effective method when you want to easily publish an extension to multiple users across organizations and networks. Register a local working folder such as GitHub or Subversion as the package source.
    • Update to the latest with the configuration management function. To publish a new package to users, you need to have the repository up-to-date, but publishing does not require any special environment.

Package update

To update the package, update the version number and create the package. You can store multiple versions of the same package Id in the package source folder.

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

For example, if the file structure in the package source folder looks like this, you have the MyExtA and MyExtB packages, each publishing two versions.

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

  1. When you publish a new version, you can see the notification icon on the status bar of Next Design that there are packages that can be updated.

  1. Click the icon to display the [Manage Extensions] dialog. You can check which packages have updates, so you can update by clicking the [Update] button.

Advanced topics

This section covers advanced topics related to package distribution.

Register the project to be displayed on the start page

You can display it on the Next Design start page by placing the sample or template Next Design project files in the pkgContents folder in your Visual Studio project.

  1. Register the sample or template project to be displayed on the start page in the pkgContents folder.

note
  • You don't need to set the file properties to copy to the output directory.
  • Make a new copy of the project file for both the sample and the template. There is no big difference in behavior, but when distributing a profile, it is recommended to distribute it in template format.

International support for packages

You can set multiple languages ​​for the title and description as follows: The appropriate language is automatically selected and displayed in the UI according to the current UI display language.

  1. Enter the international package information.

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

  2. The display text of the package will switch according to the display language of Next Design.

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

Specify the version of Next Design that works

To specify the version of Next Design, specify the version of Next Design that works with the -v argument when building the package. It will work with this version and above.

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

The build result looks like this:

Prepare your own package publishing server

The servers in the Next Design package are compliant with the NuGet V2 / V3 protocol. To release a server that is accessible only to a limited number of users, such as your organization, you need to prepare your own NuGet server. See Microsoft's Hosting His Own NuGet Feeds for more information.

Folder structure in the package

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

.\extension\
  2.0\
    NdExt1\
        sampleExtension.dll
        markdig.dll

To support multiple Next Design versions:

.\extension\
  2.0\
    sampleExtension.dll
    markdig.dll
    manifest.json
  2.5\
    sampleExtension.dll
    markdig.dll
    manifest.json

To place multiple extensions, place them as follows.

.\extensions\
  2.0\
    Ext1\
      images\
        xx.png
      ext1.dll
      manifest.json
    Ext2\
      images\
        xx.png
      ext2.dll
      manifest.json
  
.\samples\
  2.0\
    aaa.nprot

.\template\
  2.5\
    aaa.nprot
    bbb.nprot

How to create a package using other tools

The Next Design package uses the NuGet mechanism. Therefore, besides using Visual Studio and NDExt, there are the following methods.

Last updated on