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 content such as 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
• Version management is easy because multiple versions of extensions can be distributed.
• 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 8.0 SDK.

dotnet tool install --global NDExt

2. 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 (../dev-with-vs/create-vs-project.md).

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 item	Description
Package ID	A unique name that distinguishes the package. Specify it as "MyCompany.SomePackage". Use only letters, ., and numbers. It corresponds to ① in the figure below.
Package version	Used as a version to identify the package. For example, “1.0.0”. It corresponds to ③ in the figure below.
Creator	Information about the creator of the package. Please enter the company name, etc.
Description	Used 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 URL	This 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 looks like this.

• The number under the extensions folder is the corresponding Next Design version. The extension binaries to be distributed are 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.

• Profiles can be registered in packages and distributed. When you create a project file with NDExt new, a profiles folder is created in the pkgContents folder, so place the profile files (.iprof/.nprof) under that folder and in its subfolders. There are no rules for placing them in the folder, so you can place them anywhere. You can also place multiple profile files, such as different versions. When you build a package with ndext pack, they will be automatically registered in the package.

Caution

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

Publishing a package

Add a package source from the [Settings] 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.

• Press the [Settings] button to display the [Extension Settings] dialog, and press the [Add] button.

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

2. Copy the package to the package source.

Copy the built nupkg file to the package source folder.

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

Now you can publish the package as a Next Design extension.

Tips

The following methods can be considered 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 that stores .nupkg as the package source.
• Share the folder on OneDrive, GoogleDrive, etc.
• This is a method for sharing with external networks via the cloud. Create a folder on the cloud drive that contains .nupkg 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 when multiple users are familiar with Git and 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. You can store multiple versions with the same package ID in the package source folder.

1. Change the package version in the project settings to the new version. For example, if it is "1.1.0", change it to "1.2.0".
2. Build the package.
3. The .nupkg file you created is assumed to be 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, 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

4. When you publish a new version, you can see a notification icon on the status bar of Next Design to confirm that there is a package that can be updated.

5. 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

Here we will explain advanced topics regarding distribution by package.

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 operation, but if you are distributing a profile, we recommend distributing it in template format.

Internationalize your package

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 international package information.

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

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

3. If you check it in NuGet Package Explorer, you will see that the Description is as follows.

Specify the version of Next Design that will work

To specify the version of Next Design, specify the version of Next Design that will work 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's package server complies 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.