演练：通过命令行发布 Visual Studio 扩展

项目
10/10/2023

本演练演示如何使用命令行将 Visual Studio 扩展发布到 Visual Studio 市场。将扩展添加到市场时，开发人员可以使用“扩展”和“汇报”对话框来浏览新扩展和更新的扩展。

VsixPublisher.exe 是用于将 Visual Studio 扩展发布到市场的命令行工具。可以从 ${VSInstallDir}\VSSDK\VisualStudioIntegration\Tools\Bin\VsixPublisher.exe 访问它。此工具上的可用命令包括： publish、 deletePublisher、 deleteExtension、 login、 logout。

命令

发布...

将扩展发布到市场。该扩展可以是 vsix、exe/msi 文件或链接。如果扩展已存在同一版本，它将覆盖该扩展。如果扩展尚不存在，它将创建新的扩展。

命令选项	说明
有效负载（必需）	要发布的有效负载的路径或用作“更多信息 URL”的链接。
publishManifest （必需）	要使用的发布清单文件的路径。
ignoreWarnings	发布扩展时要忽略的警告列表。发布扩展时，这些警告显示为命令行消息。（例如，“VSIXValidatorWarning01， VSIXValidatorWarning02”）
personalAccessToken	用于对发布者进行身份验证的个人访问令牌（PAT）。如果未提供，则从已登录的用户获取 PAT。

VsixPublisher.exe publish -payload "{path to vsix}" -publishManifest "{path to vs-publish.json}" -ignoreWarnings "VSIXValidatorWarning01,VSIXValidatorWarning02"

deletePublisher

删除市场上的发布者。

命令选项	说明
publisherName （必需）	发布者的名称（例如标识符）。
personalAccessToken （必需）	用于对发布者进行身份验证的个人访问令牌。

VsixPublisher.exe deletePublisher -publisherName "{Publisher Name}" -personalAccessToken "{Personal Access Token}"

deleteExtension

从市场中删除扩展。

命令选项	说明
extensionName （必需）	要删除的扩展的名称。
publisherName （必需）	发布者的名称（例如标识符）。
personalAccessToken	用于对发布者进行身份验证的个人访问令牌。如果未提供，则从已登录的用户获取 pat。

VsixPublisher.exe deleteExtension -extensionName "{Extension Name}" -publisherName "{Publisher Name}"

将发布者记录到计算机中。

命令选项	说明
personalAccessToken （必需）	用于对发布者进行身份验证的个人访问令牌。
publisherName （必需）	发布者的名称（例如标识符）。
overwrite	指定应使用新的个人访问令牌覆盖任何现有发布者。

VsixPublisher.exe login -personalAccessToken "{Personal Access Token}" -publisherName "{Publisher Name}"

logout

将发布者从计算机中记录出来。

命令选项	说明
publisherName （必需）	发布者的名称（例如标识符）。
ignoreMissingPublisher	指定如果指定的发布者尚未登录，则该工具不应出错。

VsixPublisher.exe logout -publisherName "{Publisher Name}"

createPublisher

注意

此命令不再可用。可以通过导航到 Visual Studio Marketplace 创建新的发布者。

publishManifest 文件

publishManifest 文件由 publish 命令使用。它表示市场需要知道的扩展的所有元数据。如果上传的扩展来自 VSIX 扩展，则“identity”属性必须只有“internalName”集。这是因为可以从 vsixmanifest 文件生成其余的“标识”属性。如果扩展是 msi/exe 或链接扩展，则用户必须在“标识”属性中提供必填字段。清单的其余部分包含特定于市场的信息（例如类别、Q&A 是否已启用等）。

VSIX 扩展 publishManifest 文件示例：

{
    "$schema": "http://json.schemastore.org/vsix-publish",
    "categories": [ "build", "coding" ],  // The categories of the extension. Between 1 and 3 categories are required.
    "identity": {
        "internalName": "MyVsixExtension" // If not specified, we try to generate the name from the display name of the extension in the vsixmanifest file.
                                            // Required if the display name is not the actual name of the extension.
    },
    "overview": "overview.md",            // Path to the "readme" file that gets uploaded to the Marketplace. Required.
    "priceCategory": "free",              // Either "free", "trial", or "paid". Defaults to "free".
    "publisher": "MyPublisherName",       // The name of the publisher. Required.
    "private": false,                     // Specifies whether or not the extension should be public when uploaded. Defaults to false.
    "qna": true,                          // Specifies whether or not the extension should have a Q&A section. Defaults to true.
    "repo": "https://github.com/MyPublisherName/MyVsixExtension" // Not required.
}

MSI/EXE 或 LINK publishManifest 文件示例：

{
    "$schema": "http://json.schemastore.org/vsix-publish",
    "categories": [ "build", "coding" ],
    "identity": {
        "description": "My extension.", // The description of the extension. Required for non-vsix extensions.
        "displayName": "My Extension",  // The display name of the extension. Required for non-vsix extensions.
        "icon": "\\path\\to\\icon.ico", // The path to an icon file (can be relative to the json file location). Required for non-vsix extensions.
        "installTargets": [             // The installation targets for the extension. Required for non-vsix extensions.
            {
                "sku": "Microsoft.VisualStudio.Community",
                "version": "[10.0, 16.0)"
            }
        ],
        "internalName": "MyExtension",
        "language": "en-US",            // The default language id of the extension. Can be in the "1033" or "en-US" format. Required for non-vsix extensions.
        "tags": [ "tag1", "tag2" ],     // The tags for the extension. Not required.
        "version": "3.7.0",             // The version of the extension. Required for non-vsix extensions.
        "vsixId": "MyExtension",        // The vsix id of the extension. Not required but useful for showing updates to installed extensions.
    },
    "overview": "overview.md",
    "priceCategory": "free",
    "publisher": "MyPublisherName",
    "private": false,
    "qna": true,
    "repo": "https://github.com/MyPublisherName/MyVsixExtension"
}

资产文件

可以提供资产文件来嵌入自述文件中的图像等内容。例如，如果扩展具有以下“概述”Markdown 文档：

TestExtension
...
This is test extension.
![Test logo](images/testlogo.png "Test logo")

为了解析上一示例中的“images/testlogo.png”，用户可以在其发布清单中提供“assetFiles”，如下所示：

{
    "assetFiles": [
        {
            "pathOnDisk": "\\path\\to\\logo.png",
            "targetPath": "images/logo.png"
        }
    ],
    // other required fields
}

发布演练

先决条件

要按照本演练的步骤操作，必须安装 Visual Studio SDK。有关详细信息，请参阅安装 Visual Studio SDK。

创建 Visual Studio 扩展

在这种情况下，我们将使用默认的 VSPackage 扩展，但对于每种类型的扩展，相同的步骤都有效。

在 C# 中创建具有菜单命令的名为“TestPublish”的 VSPackage。有关详细信息，请参阅创建第一个扩展：Hello World。

打包扩展

使用有关产品名称、作者和版本的正确信息更新扩展 vsixmanifest。
在发布模式下生成扩展。现在，扩展将打包为 \bin\Release 文件夹中的 VSIX。
可以双击 VSIX 来验证安装。

测试扩展

在分发扩展、生成和测试该扩展之前，请确保它在 Visual Studio 的实验实例中正确安装。

在 Visual Studio 中，开始调试。打开 Visual Studio 的实验实例。
在实验实例中，转到“工具”菜单，然后单击“扩展”并汇报...。TestPublish 扩展应显示在中心窗格中并启用。
在 “工具” 菜单上，确保看到测试命令。

通过命令行将扩展发布到市场

请确保已生成扩展的发布版本，并且该版本是最新的。
请确保已创建 publishmanifest.json 和 overview.md 文件。
打开命令行并导航到 ${VSInstallDir}\VSSDK\VisualStudioIntegration\Tools\Bin\ 目录。

若要发布新扩展，请使用以下命令：

VsixPublisher.exe publish -payload "{Path to vsix file}"  -publishManifest "{path to publishManifest file}"  -personalAccessToken "{Personal Access Token that is used to authenticate the publisher. If not provided, the pat is acquired from the logged-in users.}"

成功发布扩展后，会看到以下命令行消息：
```
Uploaded 'MyVsixExtension' to the Marketplace.
```
可以通过导航到 Visual Studio Marketplace 来验证已发布的新扩展

从 Visual Studio Marketplace 安装扩展

发布扩展后，请在 Visual Studio 中进行安装和测试。

在 Visual Studio 的“工具”菜单上，单击“扩展”并汇报...“。
单击“联机”，然后搜索 TestPublish。
单击“下载”。然后，将计划扩展进行安装。
若要完成安装，请关闭 Visual Studio 的所有实例。

删除扩展

可以从 Visual Studio Marketplace 和计算机中删除扩展。

通过命令行从市场中删除扩展

如果要删除扩展，请使用以下命令：

VsixPublisher.exe deleteExtension -publisherName "TestVSIXPublisher" -extensionName "MyVsixExtension"

成功删除扩展后，会看到以下命令行消息：
```
Removed 'MyVsixExtension' from the Marketplace.
```

从计算机中删除扩展

在 Visual Studio 的“工具”菜单中，单击“扩展和更新”。
选择“MyVsixExtension”，然后单击“ 卸载”。然后，将计划扩展进行卸载。
若要完成卸载，请关闭 Visual Studio 的所有实例。

通过