Vorgehensweise: Migrieren von Erweiterungsprojekten zu Visual Studio 2017How to: Migrate extensibility projects to Visual Studio 2017

Dieses Dokument erläutert das upgrade von Erweiterungsprojekten zu Visual Studio 2017.This document explains how to upgrade extensibility projects to Visual Studio 2017. Zusätzlich zu beschreiben, wie Sie die Projektdateien zu aktualisieren, beschreibt es auch von der Erweiterung manifest der Version 2 (v2 VSIX) auf die neue Version 3 VSIX-Manifestformat (VSIX v3) aktualisieren.In addition to describing how to update the project files, it also describes how to upgrade from extension manifest version 2 (VSIX v2) to the new version 3 VSIX manifest format (VSIX v3).

Installieren von Visual Studio 2017 mit erforderlichen arbeitsauslastungenInstall Visual Studio 2017 with required workloads

Stellen Sie sicher, dass die Installation die folgenden Workloads enthält:Make sure your installation includes the following workloads:

  • .NET-Desktopentwicklung.NET desktop development
  • Entwicklung von Visual Studio-ErweiterungenVisual Studio extension development

Öffnen Sie die VSIX-Projektmappe in Visual Studio 2017Open VSIX Solution in Visual Studio 2017

Alle VSIX-Projekte müssen ein unidirektionales Upgrade der Hauptversion zu Visual Studio 2017.All VSIX projects will require a major version one-way upgrade to Visual Studio 2017.

Die Projektdatei (z. B. *csproj) aktualisiert werden:The project file (for example *.csproj) will be updated:

  • MinimumVisualStudioVersion - now set to 15.0MinimumVisualStudioVersion - now set to 15.0
  • OldToolsVersion (wenn zuvor vorhanden ist) – jetzt auf 14.0 festgelegt.OldToolsVersion (if previously exists) - now set to 14.0

Aktualisieren von NuGet-Paket Microsoft.VSSDK.BuildToolsUpdate the Microsoft.VSSDK.BuildTools NuGet package

Note

Wenn Ihre Lösung nicht über die NuGet-Paket Microsoft.VSSDK.BuildTools verweist, können Sie diesen Schritt überspringen.If your solution does not reference the Microsoft.VSSDK.BuildTools NuGet package, you can skip this step.

Um die Erweiterung in die neue VSIX v3 zu erstellen (Version 3)-Format, Ihre Lösung mit den neuen VSSDK-Build-Tools erstellt werden müssen.In order to build your extension in the new VSIX v3 (version 3) format, your solution will need to be built with the new VSSDK Build Tools. Dies wird mit Visual Studio 2017 installiert, aber Ihre VSIX-v2-Erweiterung kann einen Verweis auf eine ältere Version über NuGet belegen.This will be installed with Visual Studio 2017, but your VSIX v2 extension might be holding a reference to an older version via NuGet. Wenn dies der Fall ist, müssen Sie ein Update des NuGet-Paket Microsoft.VSSDK.BuildTools für Ihre Lösung manuell zu installieren.If so, you will need to manually install an update of the Microsoft.VSSDK.BuildTools NuGet package for your solution.

So aktualisieren Sie die NuGet-Verweise auf Microsoft.VSSDK.BuildTools:To update the NuGet references to Microsoft.VSSDK.BuildTools:

  • Mit der rechten Maustaste auf die Projektmappe, und wählen Sie NuGet-Pakete für Projektmappe verwalten.Right-click on the solution and choose Manage NuGet Packages for Solution.
  • Navigieren Sie zu der Updates Registerkarte.Navigate to the Updates tab.
  • Wählen Sie Microsoft.VSSDK.BuildTools (neueste Version) .Select Microsoft.VSSDK.BuildTools (latest version).
  • Drücken Sie Update.Press Update.

VSSDK-Buildtools

Nehmen Sie Änderungen an der VSIX-erweiterungsmanifests.Make changes to the VSIX extension manifest

Um sicherzustellen, dass der Benutzer die Installation von Visual Studio alle Assemblys, die zum Ausführen der Erweiterung erforderlich ist, geben Sie alle erforderlichen Komponenten oder Pakete in der Manifestdatei für die Erweiterung ein.To ensure that the user's installation of Visual Studio has all the assemblies required to run the extension, specify all the prerequisite components or packages in the extension manifest file. Wenn ein Benutzer versucht, die die Erweiterung zu installieren, überprüft der VSIX-Installationsprogramm, um festzustellen, ob alle erforderlichen Komponenten installiert sind.When a user attempts to install the extension, the VSIXInstaller will check to see if all the prerequisites are installed. Wenn einige fehlen, wird der Benutzer aufgefordert werden, um die fehlenden Komponenten im Rahmen des Installationsvorgangs Erweiterung zu installieren.If some are missing, the user will be prompted to install the missing components as part of the extension installation process.

Note

Zumindest sollten alle Erweiterungen der Visual Studio-Kern-Editor-Komponente als erforderliche Komponente angeben.At a minimum, all extensions should specify the Visual Studio core editor component as a prerequisite.

  • Bearbeiten Sie die Erweiterung manifest-Datei (in der Regel aufgerufen "Source.Extension.vsixmanifest" ).Edit the extension manifest file (usually called source.extension.vsixmanifest).
  • Stellen Sie sicher InstallationTarget 15.0 umfasst.Ensure InstallationTarget includes 15.0.
  • Fügen Sie die erforderlichen Installationsvoraussetzungen hinzu (wie im folgenden Beispiel gezeigt).Add required installation prerequisites (as shown in the example below).

Beispiel:Example:

<PackageManifest>
 ...
    <Prerequisites>
        <Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="[15.0,16.0)" />
        <Prerequisite Id="Microsoft.VisualStudio.Component.DiagnosticTools" Version="[15.0.25814.0,16.0)" />
        <Prerequisite Id="Microsoft.VisualStudio.Shell.12.0" Version="[12.0]" />
    </Prerequisites>
 ...
</PackageManifest>

Option: Verwenden Sie den Designer, um die VSIX-erweiterungsmanifests zu ändernOption: Use the designer to make changes to the VSIX extension manifest

Anstatt das manifest-XML direkt zu bearbeiten, können Sie die neue Voraussetzungen Registerkarte im Manifest-Designer, wählen Sie die Voraussetzungen und den XML-Code für Sie aktualisiert werden.Instead of directly editing the manifest XML, you can use the new Prerequisites tab in the Manifest Designer to select the prerequisites and the XML will be updated for you.

Note

Der Manifest-Designer lässt nur das Auswählen von Komponenten (nicht "Workloads" oder "Pakete"), die in der aktuellen Visual Studio-Instanz installiert sind.The Manifest Designer will only allow you to select Components (not Workloads or Packages) that are installed on the current Visual Studio instance. Wenn Sie eine Voraussetzung für eine Workload hinzufügen müssen, bearbeiten Paket oder einer Komponente, die derzeit nicht installiert ist, das Manifest-XML direkt.If you need to add a prerequisite for a workload, package, or component that is not currently installed, edit the manifest XML directly.

  • Open "Source.Extension.vsixmanifest" [Entwurf] Datei.Open source.extension.vsixmanifest [Design] file.

  • Wählen Sie Voraussetzungen Registerkarte, und drücken Sie neu Schaltfläche.Select Prerequisites tab and press New button.

    VSIX-manifest-designer

  • Die neue Voraussetzung hinzufügen Fenster wird geöffnet.The Add New Prerequisite window will open.

    Fügen Sie die VSIX-Voraussetzungen

  • Klicken Sie auf das Dropdownmenü für Namen , und wählen Sie die gewünschte Voraussetzung.Click on the dropdown for Name and select the desired prerequisite.

  • Aktualisieren Sie die Version aus, falls erforderlich.Update the version if necessary.

    Note

    Das Versionsfeld werden vorab ausgefüllt, mit der Version der derzeit installierten Komponente mit einem Bereich umfasst bis zu (aber nicht einschließlich) der nächsten Hauptversion von der Komponente.The version field will be pre-populated with the version of the currently installed component, with a range spanning up to (but not including) the next major version of the component.

    Hinzufügen der Roslyn-Voraussetzungen

  • Klicken Sie auf OK.Press OK.

Debug-Einstellungen für das Projekt aktualisierenUpdate Debug settings for the project

Wenn Sie Ihre Erweiterung in einer experimentellen Instanz von Visual Studio debuggen möchten, stellen sicher, dass die projekteinstellungen für Debuggen > Startaktion hat die externe starten Programm: Wert festgelegt wird, um die devenv.exe Datei der Visual Studio 2017-Installation.If you wish to debug your extension in an experimental instance of Visual Studio, make sure that the project settings for Debug > Start action has the Start external program: value set to the devenv.exe file of your Visual Studio 2017 installation.

Dies kann so aus: C:\Programme\Microsoft Dateien (x86) \Microsoft Visual Studio\2017\Enterprise\Common7\IDE\devenv.exeIt might look like: C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\devenv.exe

Externes Programm starten

Note

Debuggen von Startaktion befindet sich in der Regel in der . csproj.user Datei.The Debug Start Action is typically stored in the .csproj.user file. Diese Datei befindet sich in der Regel in der ".gitignore" Datei, und daher nicht Normal gespeichert mit anderen Projektdateien, wenn ein Commit in die quellcodeverwaltung ausgeführt.This file is usually included in the .gitignore file and, hence, is not normally saved with other project files when committed to source control. Wenn Sie die Projektmappe aus der quellcodeverwaltung neue abgerufen haben ist es wahrscheinlich das Projekt keine Werte für Startaktion festgelegt hat.As such, if you have pulled your solution fresh from source control it is likely the project will have no values set for Start Action. Neue VSIX-Projekte mit Visual Studio 2017 erstellt haben eine . csproj.user Datei erstellt, die mit den Standardeinstellungen für das aktuelle Visual Studio-Installationsverzeichnis verweist.New VSIX projects created with Visual Studio 2017 will have a .csproj.user file created with defaults pointing to the current Visual Studio install directory. Wenn Sie eine VSIX-Erweiterung v2 migrieren, es jedoch wahrscheinlich ist, die die . csproj.user -Datei enthält Verweise auf der früheren Version des Visual Studio-Installationsverzeichnis.However if you are migrating a VSIX v2 extension, it is likely that the .csproj.user file will contain references to the previous Visual Studio version's install directory. Festlegen des Werts für Debuggen > Startaktion ermöglicht die richtige experimentelle Visual Studio-Instanz zum Starten, wenn Sie versuchen, Ihre Erweiterung zu debuggen.Setting the value for Debug > Start action will allow the correct Visual Studio experimental instance to launch when you try to debug your extension.

Überprüfen Sie, dass die Erweiterung (wie eine VSIX v3) erstellt.Check that the extension builds correctly (as a VSIX v3)

  • Erstellen Sie das VSIX-Projekt.Build the VSIX project.
  • Entzippen Sie die generierte VSIX-Datei aus.Unzip the generated VSIX.
    • Standardmäßig befindet sich die VSIX-Datei in Bin/Debug oder Bin/Release als [YourCustomExtension] VSIX.By default, the VSIX file lives inside bin/Debug or bin/Release as [YourCustomExtension].vsix.
    • Benennen Sie VSIX zu ZIP , einfach den Inhalt anzuzeigen.Rename .vsix to .zip to easily view the contents.
  • Überprüfen Sie das Vorhandensein von drei Dateien:Check for the existence of three files:
    • extension.vsixmanifestextension.vsixmanifest
    • manifest.jsonmanifest.json
    • catalog.jsoncatalog.json

Überprüfen Sie, wenn alle erforderliche Komponenten installiert sindCheck when all required prerequisites are installed

Test, der die VSIX-Datei auf einem Computer mit allen erforderlichen Komponenten installiert wurde erfolgreich installiert.Test that the VSIX installs successfully on a machine with all required prerequisites installed.

Note

Vor der Installation alle Erweiterungen, beenden Sie alle Instanzen von Visual Studio.Before installing any extension, please shut down all instances of Visual Studio.

Versucht, die die Erweiterung zu installieren:Attempt to install the extension:

  • Für Visual Studio 2017On Visual Studio 2017

VSIX-Installer für Visual Studio 2017

  • Optional: Überprüfen Sie in früheren Versionen von Visual Studio.Optional: Check on previous versions of Visual Studio.
    • Stellt die Abwärtskompatibilität zu gewährleisten.Proves backward compatibility.
    • Sollte funktionieren für Visual Studio 2012, Visual Studio 2013, Visual Studio 2015.Should work for Visual Studio 2012, Visual Studio 2013, Visual Studio 2015.
  • Optional: Überprüfen Sie, dass die VSIX-Installer-Version aus eine Auswahl von Versionen bietet.Optional: Check that VSIX Installer Version Checker offers a choice of versions.
    • Enthält frühere Versionen von Visual Studio (falls installiert).Includes previous versions of Visual Studio (if installed).
    • Enthält Visual Studio 2017.Includes Visual Studio 2017.

Wenn Visual Studio zuletzt geöffnet wurde, wird möglicherweise ein Dialogfeld wie folgt angezeigt:If Visual Studio was recently opened, you might see a dialog box like this:

Visual Studio ausgeführte Prozesse

Warten Sie, bis die Prozesse beendet, oder beenden Sie die Tasks manuell.Wait for the processes to shut down, or manually end the tasks. Sie finden die Prozesse durch den aufgeführten Namen oder mit der PID, die in Klammern aufgeführt.You can find the processes by the listed name, or with the PID listed in parenthesis.

Note

Diese Prozesse werden nicht automatisch heruntergefahren, während eine Instanz von Visual Studio ausgeführt wird.These processes will not automatically shut down while an instance of Visual Studio is running. Stellen Sie sicher, dass Sie alle Instanzen von Visual Studio auf dem Computer – einschließlich der von anderen Benutzern oder beendet haben, dann zu wiederholen.Ensure that you've shut down all instances of Visual Studio on the machine - including those from other users, then continue to retry.

Überprüfen Sie, wenn die erforderlichen Komponenten fehlt.Check when missing the required prerequisites

  • Versuchen Sie zum Installieren der Erweiterung auf einem Computer mit Visual Studio 2017, enthalten nicht alle Komponenten, die im Rahmen der Vorbereitung (oben) definiert.Attempt to install the extension on a machine with Visual Studio 2017 that DOES NOT CONTAIN all the components defined in the Prerequisites (above).
  • Überprüfen Sie, dass die Installation die fehlende Komponente/s identifiziert und sie als erforderliche Komponente für das VSIX-Installationsprogramm listet an.Check that the installation identifies the missing component/s and lists them as a prerequisite in the VSIXInstaller.
  • Hinweis: Erhöhung der Rechte ist erforderlich, wenn alle erforderlichen Komponenten mit der Erweiterung installiert werden müssen.Note: Elevation will be required if any prerequisites need to be installed with the extension.

VSIX-Installationsprogramm fehlende erforderliche Komponente

Entscheiden Sie sich für KomponentenDecide on components

Beim Nachschlagen von Abhängigkeiten, werden Sie feststellen, dass eine Abhängigkeit für mehrere Komponenten zuordnen konnte.When looking up your dependencies, you will find that one dependency could map to multiple components. Um zu bestimmen, welche Abhängigkeiten Sie angeben, wie Ihre Voraussetzung ist sollten, es wird empfohlen, dass Sie eine Komponente auswählen, die zu Ihrer Erweiterung vergleichbare Funktion, und, berücksichtigen auch Ihre Benutzer und welche Art von Komponenten würden sie in den meisten Fällen installiert haben oder wäre nicht installieren sollten.To determine which dependencies you should specify as your prerequisite, we suggest that you choose a component that has a functionality similar to your extension and to also consider your users and what type of components would they most likely have installed or wouldn't mind installing. Es wird empfohlen, erstellen, die Ihre Erweiterungen in einer Weise, in denen die erforderlichen Komponenten nur das Minimum erfüllen können, das die Erweiterung ausgeführt werden kann, und für zusätzliche Features lassen werden inaktiv, wenn sicher, dass Komponenten nicht erkannt werden.We also suggest building your extensions in a way where the required prerequisites satisfy only the minimum that will allow your extension to run and for additional features have them be dormant if certain components are not detected.

Um weitere Hilfestellung zu bieten, haben wir einige allgemeine Erweiterungstypen und ihre Vorkenntnisse identifiziert:To provide further guidance, we have identified a few common extension types and their suggested prerequisites:

ErweiterungstypExtension Type AnzeigenameDisplay Name IDID
EditorEditor Visual Studio-Kern-EditorVisual Studio core editor Microsoft.VisualStudio.Component.CoreEditorMicrosoft.VisualStudio.Component.CoreEditor
RoslynRoslyn C# und Visual BasicC# and Visual Basic Microsoft.VisualStudio.Component.Roslyn.LanguageServicesMicrosoft.VisualStudio.Component.Roslyn.LanguageServices
WPFWPF Core für Arbeitsauslastung verwalteter DesktopsManaged Desktop Workload Core Microsoft.VisualStudio.Component.ManagedDesktop.CoreMicrosoft.VisualStudio.Component.ManagedDesktop.Core
DebuggerDebugger Just-In-Time-DebuggerJust-In-Time debugger Microsoft.VisualStudio.Component.Debugger.JustInTimeMicrosoft.VisualStudio.Component.Debugger.JustInTime

Suchen Sie die Komponenten-IDsFind component IDs

Die Liste der Komponenten, sortiert nach Visual Studio-Produkt ist unter arbeitsauslastungs- und Komponenten-IDs von Visual Studio 2017.The list of components sorted by Visual Studio product is at Visual Studio 2017 workload and component IDs. Verwenden Sie diese Komponenten-IDs für Ihren erforderlichen Komponenten-IDs im Manifest an.Use these component IDs for your prerequisite IDs in your manifest.

Wenn Sie nicht sicher sind, welche Komponente eine bestimmte Binärdatei enthält, laden Sie die binäres Mapping-Arbeitsblatt-Komponente >.If you are unsure which component contains a specific binary, download the Component -> Binary mapping spreadsheet.

Visual Studio 2017-ComponentBinaryMapping.xlsxvs2017-ComponentBinaryMapping.xlsx

Es gibt vier Spalten im Excel-Arbeitsblatt ein: Name der Komponente, ComponentId, Version, und Binary / Dateinamen.There are four columns in the Excel sheet: Component Name, ComponentId, Version, and Binary / File Names. Sie können die Filter verwenden, die Suche nach bestimmten Komponenten und -Binärdateien.You can use the filters to search and find specific components and binaries.

Für alle Ihre Verweise zunächst bestimmen Sie, welche in der Kern-Editor (Microsoft.VisualStudio.Component.CoreEditor) Komponente sind.For all your references, first determine which ones are in the core editor (Microsoft.VisualStudio.Component.CoreEditor) component. Zumindest müssen die Kern-Editor-Komponente als Voraussetzung für alle Erweiterungen angegeben werden.At minimum, we require the core editor component to be specified as a prerequisite for all extensions. Verweise, die beibehalten werden, deren nicht-Kern-Editor, fügen Sie Filter in der Binärdateien / Dateinamen Abschnitt aus, um Komponenten zu finden, die die Teilmengen der diese Verweise.Of the references that are left that are not in core editor, add filters in the Binaries / Files Names section to find components that have any of the subsets of those references.

Beispiele:Examples:

  • Wenn Sie eine Debuggererweiterung und wissen, dass Ihr Projekt einen Verweis auf VSDebugEng.dll und VSDebug.dll, klicken Sie auf die Schaltfläche "Filter" in der Binärdateien / DateinamenHeader.If you have a debugger extension and know that your project has a reference to VSDebugEng.dll and VSDebug.dll, click on the filter button in the Binaries / Files Names header. Suchen Sie nach "VSDebugEng.dll", und wählen Sie OK.Search for "VSDebugEng.dll" and select OK. Klicken Sie dann auf, auf die Schaltfläche "Filter" in der Binärdateien / Dateinamen Header erneut aus und suchen Sie nach "VSDebug.dll".Next click on the filter button in the Binaries / Files Names header again and search for "VSDebug.dll". Aktivieren Sie das Kontrollkästchen fügen Sie die aktuelle Auswahl dem filter , und wählen Sie OK.Select the checkbox Add current selection to filter and select OK. Durchsuchen Sie jetzt die Komponentenname eine Komponente suchen, die am meisten im Zusammenhang mit der Ihr Erweiterungstyp.Now look through the Component Name to find a component that is most related to your extension type. In diesem Beispiel würde gewählten die Just-In-Time-debugger und Ihre Vsixmanifest hinzuzufügen.In this example, you would chose the Just-In-Time debugger and add it to your vsixmanifest.
  • Wenn Sie wissen, dass Ihr Projekt mit dem Debugger-Elemente behandelt, können Sie suchen, klicken Sie auf "Debuggen" in das filtersuchfeld um festzustellen, welche Komponenten Debugger im Namen enthalten.If you know that your project deals with debugger elements, you can search on "debugger" in the filter search box to see what components contain debugger in its name.

Geben Sie ein Visual Studio 2017-releaseSpecify a Visual Studio 2017 release

Wenn die Erweiterung eine bestimmte Version von Visual Studio 2017 erforderlich sind, z. B. ein Feature in Version 15.3 hängt, müssen Sie die Nummer des Builds in VSIX Einbeziehen angeben "installationtarget" .If your extension requires a specific version of Visual Studio 2017, for example, it depends on a feature released in 15.3, you must specify the build number in your VSIX InstallationTarget. Beispielsweise hat in Version 15.3 eine Buildnummer von "15.0.26730.3".For example, release 15.3 has a build number of '15.0.26730.3'. Sehen Sie die Zuordnung von Releases fest, erstellen Sie Zahlen hier.You can see the mapping of releases to build numbers here. Verwenden die Versionsnummer "15.3" ist nicht funktionsfähig.Using the release number '15.3' will not work correctly.

Wenn Ihre Erweiterung erforderlich, Version 15.3 ist oder höher verwenden, müssten Sie deklarieren die "installationtarget" Version als [15.0.26730.3, 16.0):If your extension requires 15.3 or higher, you would declare the InstallationTarget Version as [15.0.26730.3, 16.0):

<Installation>
  <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[15.0.26730.3, 16.0)" />
</Installation>