Skip to main content

Distribution by package function

Extensions can be distributed by package function in addition to direct distribution by binary. By using the package function, it is easy for other users to use extensions and samples after version control. Packages can be distributed by Next Design extensions.

Packaging and its benefits​

Packaging is the process of creating Next Design extensions in a file format that can be distributed. This makes distributing and updating extensions very simple. The main benefits are as follows:

  • Easy installation and update
  • Extensions can be installed, uninstalled, and updated with one click.
  • Users can be notified on the Next Design screen when a new version is released.
  • Easy version management
  • Multiple versions of extensions can be distributed, making version management easy.
  • Package overview and changes by version can be displayed on the Next Design screen.
  • Extensions that work with specific Next Design versions can be developed.
  • No dedicated server required for distribution
  • Custom package deployment folders can be registered, allowing simple distribution using network folders or version management tools such as GitHub/GitLab and Subversion.
  • Profiles and samples can be distributed
  • Not limited to extensions, profiles and project templates can be distributed.

Context​

Prepare the tools and environment required for packaging. Skip if already installed.

  1. Install NDExt.

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

dotnet tool install --global NDExt
  1. Create an extension project in Visual Studio using project template.

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

dotnet new --install NextDesign.Extension.ProjectTemplates

Creating a package​

There are several ways to create a Next Design extension package, but the simplest method is to use Visual Studio and the command line tool NDExt. Here, we will explain how to set it up using Visual Studio in the following order.

  1. Create an extension project in Visual Studio.

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

For Visual Studio 2022, the dialog looks like this.

The explanation of each property is as follows.

Setting itemDescription
Package IDA unique name that distinguishes the package. Specify it as "MyCompany.SomePackage". Use only letters, ., 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.
CreatorInformation about the creator of the package. Please enter the company name, etc.
DescriptionUsed for the title and description of the package. It can be any string. Only the first line is used for the title of the package, whereas the entire text is used for the description of the package. It corresponds to ② and ⑤ in the figure below.
Project URLThis is the URL of the site related to the package. It corresponds to ④ in the figure below.

It is displayed as follows in the [Packages] dialog.

Note
  • Make sure that 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 and description of the package.
  • If you want to publish a new version, update the package version. If you created it with "1.0.0", update it to 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.

Building a package​

NDExt is used to build a package.

If you run the following command on the command line, it will search for all extension projects (csproj) in the execution directory and build and package them.

C:\MyProjects\NdExt1\NdExt1> ndext pack

  • If the ndext pack command is executed successfully, a nupkg file will be created 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 extension and profile files.

When you open the nupkg file with NuGet Package Explorer, a tool that allows you to view and edit nupkg files, it will look like this.

  • 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 when registering Next Design sample 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 will be automatically registered in the package.

Note
  • Please close Next Design when building. Packaging may fail if Next Design is running.
  • If the package configuration file contains Japanese file names such as sample and template files and documents, it will fail, so please use English file names.

Publishing a package​

Add a package source from the [Setting] button of Next Design extension and place this nupkg file to publish. A package source is a directory or a web server (website) called a NuGet server. Here, we will explain the easiest way to publish using a folder as the package source.

  1. Add a package source.
  • Click [File] menu > [Packages] to open the [Packages] dialog.

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

  • Specify the folder to distribute the package to. This 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.

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

You can now publish the package as a Next Design extension.

Tips

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

  • Share in a network folder that users can access.
    • This is the simplest method for sharing only within a company or organization. Set the network folder containing .nupkg as the package source.
  • Share a folder on OneDrive, GoogleDrive, etc.
    • This is a method for sharing with external networks via the cloud. Create a folder containing .nupkg on a cloud drive and share it with multiple users. Each user sets their local drive as the package source.
  • Publish using GitHub/GitLab or Subversion.
    • This is an effective method for users who are familiar with Git, etc., and who want to publish extensions simply across organizations or networks. Register a local working folder such as GitHub or Subversion as the package source.
    • Update to the latest version using the configuration management function. To publish a new package to users, you need to have them update the repository, but no special environment is required for publishing.

Updating a package To update a package, update the version number and create a 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, change it from "1.1.0" to "1.2.0".

  2. Build the package.

  3. Let's assume that the .nupkg file you created is something 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 is as follows, there are packages MyExtA and MyExtB, each of which has two published 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 a notification icon on the status bar of Next Design to confirm that there are packages that can be updated.

  1. Click the icon to display the [Packages] dialog. You can check which packages have updates and press the [Update] button to update them.

Advanced Topics​

This section describes advanced topics related to distribution by packages.

Register a project to be displayed on the start page​

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

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

note
  • It is not necessary to set the file properties to copy to the output directory.
  • Both samples and templates create new copies of the project files. There is no significant difference in behavior, but it is recommended to distribute profiles in template format.

Make packages international​

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

  1. Enter the international package information.

In the project settings, enter text for Japanese and English like this: { "ja" : "Description in Japanese" , "en" : "english here"}. Only the first line will be used for the title, while the entire text will be used for the description.

  1. The package display text will be switched according to the display language of Next Design.

  1. Note that when you check in NuGet Package Explorer, Description will look like this.

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. This version or later will work.

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

The build result will be as follows.

Prepare your own package publishing server​

Next Design package servers comply 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 Hosting your own NuGet feed.

Folder structure in 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

If you want it to work with multiple Next Design versions, do the following.

.\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, place them as follows.

.\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 a package using other tools​

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

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