Vorgehensweise: Migrieren von Erweiterbarkeitsprojekten zu Visual Studio 2017

In diesem Dokument wird erläutert, wie Erweiterbarkeitsprojekte auf Visual Studio 2017 aktualisiert werden. Neben der Beschreibung, wie die Projektdateien aktualisiert werden, wird auch beschrieben, wie Sie ein Upgrade von Erweiterungsmanifestversion 2 (VSIX v2) auf das neue VSIX-Manifestformat der Version 3 (VSIX v3) durchführen.

Installieren von Visual Studio 2017 mit erforderlichen Workloads

Stellen Sie sicher, dass die Installation die folgenden Workloads enthält:

  • .NET-Desktopentwicklung
  • Entwicklung von Visual Studio-Erweiterungen

Öffnen der VSIX-Lösung in Visual Studio 2017

Für alle VSIX-Projekte ist ein einseitiges Upgrade der Hauptversion auf Visual Studio 2017 erforderlich.

Die Projektdatei (z.B. *CSPROJ) wird aktualisiert:

  • MinimumVisualStudioVersion – jetzt auf 15.0 festgelegt
  • OldToolsVersion (sofern bereits vorhanden) – jetzt auf 14.0 festgelegt

Aktualisieren des Pakets Microsoft.VSSDK.BuildTools NuGet

Hinweis

Wenn Ihre Projektmappe nicht auf das Paket Microsoft.VSSDK.BuildTools NuGet verweist, können Sie diesen Schritt überspringen.

Um Ihre Erweiterung im neuen VSIX v3-Format (Version 3) zu erstellen, muss Ihre Lösung mit den neuen VSSDK-Buildtools erstellt werden. Dies wird mit Visual Studio 2017 installiert, aber Ihre VSIX v2-Erweiterung kann einen Verweis auf eine ältere Version über NuGet enthalten. In diesem Falle müssen Sie ein Update des Microsoft.VSSDK.BuildTools-NuGet-Pakets für Ihre Lösung manuell installieren.

So aktualisieren Sie die NuGet Verweise auf Microsoft.VSSDK.BuildTools:

  • Klicken Sie mit der rechten Maustaste auf die Projektmappe, und wählen Sie manage NuGet Packages for Solution (NuGet Pakete für Projektmappe verwalten) aus.
  • Navigieren Sie zur Registerkarte Updates.
  • Wählen Sie Microsoft.VSSDK.BuildTools (neueste Version) aus.
  • Klicken Sie auf Aktualisieren.

VSSDK-Buildtools

Vornehmen von Änderungen am VSIX-Erweiterungsmanifest

Um sicherzustellen, dass die Installation von Visual Studio durch den Benutzer über alle Assemblys verfügt, die zum Ausführen der Erweiterung erforderlich sind, geben Sie alle erforderlichen Komponenten oder Pakete in der Erweiterungsmanifestdatei an. Wenn ein Benutzer versucht, die Erweiterung zu installieren, überprüft VSIXInstaller, ob alle erforderlichen Komponenten installiert sind. Wenn einige fehlen, wird der Benutzer im Rahmen der Erweiterungsinstallation aufgefordert, die fehlenden Komponenten zu installieren.

Hinweis

Alle Erweiterungen sollten mindestens die Visual Studio Kern-Editorkomponente als Voraussetzung angeben.

  • Bearbeiten Sie die Erweiterungsmanifestdatei (in der Regel als source.extension.vsixmanifest bezeichnet).
  • Stellen Sie sicher, dass InstallationTarget 15.0 enthält.
  • Fügen Sie erforderliche Installationsvoraussetzungen hinzu (wie im folgenden Beispiel gezeigt).
    • Es wird empfohlen, nur Komponenten-IDs für installationsvoraussetzungen anzugeben.
    • Anweisungen zum Identifizieren von Komponenten-IDsfinden Sie im Abschnitt am Ende dieses Dokuments.

Beispiel:

<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 Änderungen am VSIX-Erweiterungsmanifest vorzunehmen.

Anstatt die Manifest-XML direkt zu bearbeiten, können Sie die neue Registerkarte Voraussetzungen im Manifest-Designer verwenden, um die Voraussetzungen auszuwählen, und der XML-Code wird für Sie aktualisiert.

Hinweis

Im Manifest-Designer können Sie nur Komponenten (nicht Workloads oder Pakete) auswählen, die auf der aktuellen Visual Studio Instanz installiert sind. Wenn Sie eine Voraussetzung für eine Workload, ein Paket oder eine Komponente hinzufügen müssen, die derzeit nicht installiert ist, bearbeiten Sie die Manifest-XML direkt.

  • Open Source.extension.vsixmanifest [Design]-Datei.

  • Wählen Sie die Registerkarte Voraussetzungen aus, und klicken Sie auf Die Schaltfläche Neu.

    VSIX-Manifest-Designer

  • Das Fenster Neue Voraussetzung hinzufügen wird geöffnet.

    Hinzufügen der vsix-Voraussetzung

  • Klicken Sie auf die Dropdownliste für Name, und wählen Sie die gewünschte Voraussetzung aus.

  • Aktualisieren Sie die Version bei Bedarf.

    Hinweis

    Das Versionsfeld wird mit der Version der derzeit installierten Komponente vorab aufgefüllt, wobei sich ein Bereich bis zur nächsten Hauptversion der Komponente erstreckt (aber nicht eingeschlossen wird).

    Roslyn-Voraussetzung hinzufügen

  • Klicken Sie auf OK.

Aktualisieren der Debugeinstellungen für das Projekt

Wenn Sie Ihre Erweiterung in einer experimentellen Instanz von Visual Studio debuggen möchten, stellen Sie sicher, dass für die Projekteinstellungen für die > Aktion Debuggen start der Wert Externes Programm starten: auf die devenv.exe-Datei Ihrer Visual Studio 2017-Installation festgelegt ist.

Es könnte wie folgt aussehen: C:\Programme (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\devenv.exe

Externes Programm starten

Hinweis

Die Debugstartaktion wird in der Regel in der Datei .csproj.user gespeichert. Diese Datei ist in der Regel in der GITIGNORE-Datei enthalten und wird daher normalerweise nicht mit anderen Projektdateien gespeichert, wenn ein Commit für die Quellcodeverwaltung ausgeführt wird. Wenn Sie ihre Projektmappe also neu aus der Quellcodeverwaltung abgerufen haben, ist es wahrscheinlich, dass für das Projekt keine Werte für Aktion starten festgelegt sind. Für neue VSIX-Projekte, die mit Visual Studio 2017 erstellt wurden, wird eine CSPROJ.USER-Datei mit Standardwerten erstellt, die auf das aktuelle installationsverzeichnis Visual Studio verweisen. Wenn Sie jedoch eine VSIX v2-Erweiterung migrieren, enthält die Datei .csproj.user wahrscheinlich Verweise auf das Installationsverzeichnis der vorherigen Visual Studio Version. Wenn Sie den Wert für die Aktion Debuggen starten festlegen, > kann die richtige Visual Studio experimentelle Instanz gestartet werden, wenn Sie versuchen, die Erweiterung zu debuggen.

Überprüfen Sie, ob die Erweiterung ordnungsgemäß erstellt wird (als VSIX v3).

  • Erstellen Sie das VSIX-Projekt.
  • Entzippen Sie die generierte VSIX.
    • Standardmäßig befindet sich die VSIX-Datei in bin/Debug oder bin/Release als [YourCustomExtension].vsix.
    • Benennen Sie .vsix in .zip um, um den Inhalt einfach anzuzeigen.
  • Überprüfen Sie, ob drei Dateien vorhanden sind:
    • extension.vsixmanifest
    • manifest.jsein
    • catalog.jsein

Überprüfen Sie, ob alle erforderlichen Komponenten installiert sind.

Testen Sie, dass vsix erfolgreich auf einem Computer installiert wird, auf dem alle erforderlichen Komponenten installiert sind.

Hinweis

Fahren Sie vor der Installation einer Erweiterung alle Instanzen von Visual Studio herunter.

Versuchen Sie, die Erweiterung zu installieren:

  • Am Visual Studio 2017

VSIX-Installer auf Visual Studio 2017

  • Optional: Überprüfen Sie frühere Versionen von Visual Studio.
    • Erweist sich als abwärtskompatibel.
    • Sollte für Visual Studio 2012, Visual Studio 2013, Visual Studio 2015 funktionieren.
  • Optional: Überprüfen Sie, ob die Versionsprüfung des VSIX-Installers eine Auswahl von Versionen bietet.
    • Enthält frühere Versionen von Visual Studio (sofern installiert).
    • Enthält Visual Studio 2017.

Wenn Visual Studio kürzlich geöffnet wurde, wird möglicherweise ein Dialogfeld wie das folgende angezeigt:

Im Vergleich zu ausgeführten Prozessen

Warten Sie, bis die Prozesse heruntergefahren wurden, oder beenden Sie die Aufgaben manuell. Sie finden die Prozesse anhand des aufgelisteten Namens oder mit der PID, die in Klammern aufgeführt ist.

Hinweis

Diese Prozesse werden nicht automatisch heruntergefahren, während eine Instanz von Visual Studio ausgeführt wird. Stellen Sie sicher, dass Sie alle Instanzen von Visual Studio auf dem Computer heruntergefahren haben , einschließlich der Instanzen anderer Benutzer, und wiederholen Sie dann den Vorgang.

Überprüfen Sie, ob die erforderlichen Voraussetzungen fehlen.

  • Versuchen Sie, die Erweiterung auf einem Computer mit Visual Studio 2017 zu installieren, der NICHT alle komponenten enthält, die in den Voraussetzungen (oben) definiert sind.
  • Vergewissern Sie sich, dass die Installation die fehlenden Komponenten identifiziert und als Voraussetzung im VSIXInstaller auflistet.
  • Hinweis: Erhöhte Rechte sind erforderlich, wenn mit der Erweiterung erforderliche Komponenten installiert werden müssen.

Vsixinstaller: Erforderliche Komponente fehlt

Entscheiden über Komponenten

Wenn Sie Ihre Abhängigkeiten suchen, werden Sie feststellen, dass eine Abhängigkeit mehreren Komponenten zugeordnet werden kann. Um zu bestimmen, welche Abhängigkeiten Sie als Voraussetzung angeben sollten, empfehlen wir Ihnen, eine Komponente auszuwählen, die eine Ähnliche Funktionalität wie Ihre Erweiterung aufweist. Außerdem sollten Sie Ihre Benutzer und die Art der Komponenten berücksichtigen, die sie wahrscheinlich installiert haben oder die Installation nicht beeinträchtigen würde. Wir empfehlen auch, Ihre Erweiterungen so zu erstellen, dass die erforderlichen Voraussetzungen nur das Minimum erfüllen, das die Ausführung Ihrer Erweiterung ermöglicht, und wenn sie für zusätzliche Features ruhen, wenn bestimmte Komponenten nicht erkannt werden.

Um weitere Anleitungen bereitzustellen, haben wir einige gängige Erweiterungstypen und deren vorgeschlagene Voraussetzungen identifiziert:

Erweiterungstyp Anzeigename ID
Editor Visual Studio-Kern-Editor Microsoft.VisualStudio.Component.CoreEditor
Roslyn C# und Visual Basic Microsoft.VisualStudio.Component.Roslyn.LanguageServices
WPF Core für Arbeitsauslastung verwalteter Desktops Microsoft.VisualStudio.Component.ManagedDesktop.Core
Debugger Just-In-Time-Debugger Microsoft.VisualStudio.Component.Debugger.JustInTime

Suchen von Komponenten-IDs

Die Liste der Komponenten, die nach Visual Studio Produkt sortiert sind, befindet sich unter Visual Studio 2017 Workload- und Komponenten-IDs. Verwenden Sie diese Komponenten-IDs für die erforderlichen IDs im Manifest.

Wenn Sie nicht sicher sind, welche Komponente eine bestimmte Binärdatei enthält, laden Sie das Arbeitsblatt Component -> Binary mappingherunter.

vs2017-ComponentBinaryMapping.xlsx

Das blatt Excel enthält vier Spalten: Komponentenname, Komponenten-ID, Version und Binär-/Dateinamen. Sie können die Filter verwenden, um bestimmte Komponenten und Binärdateien zu suchen und zu suchen.

Bestimmen Sie für alle Verweise zunächst, welche sich in der Kern-Editor-Komponente (Microsoft.VisualStudio.Component.CoreEditor) befinden. Es ist mindestens erforderlich, dass die Kern-Editorkomponente als Voraussetzung für alle Erweiterungen angegeben wird. Fügen Sie unter den links gelassenen Verweisen, die sich nicht im Kern-Editor befinden, Filter im Abschnitt Binärdateien/Dateinamen hinzu, um Komponenten zu suchen, die eine der Teilmengen dieser Verweise aufweisen.

Beispiele:

  • Wenn Sie über eine Debuggererweiterung verfügen und wissen, dass Ihr Projekt über einen Verweis auf VSDebugEng.dll und VSDebug.dll verfügt, klicken Sie im Header Binärdateien/Dateinamen auf die Filterschaltfläche. Suchen Sie nach "VSDebugEng.dll", und wählen Sie OK aus. Klicken Sie als Nächstes erneut auf die Filterschaltfläche im Header Binärdateien/Dateinamen, und suchen Sie nach "VSDebug.dll". Aktivieren Sie das Kontrollkästchen Aktuelle Auswahl zum Filtern hinzufügen, und wählen Sie OK aus. Durchsuchen Sie nun den Komponentennamen, um eine Komponente zu finden, die sich am meisten auf Ihren Erweiterungstyp bezieht. In diesem Beispiel würden Sie den Just-In-Time-Debugger auswählen und dem vsixmanifest hinzufügen.
  • Wenn Sie wissen, dass ihr Projekt Debuggerelemente verarbeitet, können Sie im Filtersuchfeld nach "Debugger" suchen, um zu sehen, welche Komponenten den Debugger im Namen enthalten.

Angeben eines Visual Studio Release 2017

Wenn Ihre Erweiterung beispielsweise eine bestimmte Version von Visual Studio 2017 erfordert, hängt sie von einer in Version 15.3 veröffentlichten Funktion ab, müssen Sie die Buildnummer in Ihrer VSIX InstallationTarget angeben. Release 15.3 hat beispielsweise die Buildnummer "15.0.26730.3". Die Zuordnung von Releases zu Buildnummern finden Sie hier. Die Verwendung der Releasenummer "15.3" funktioniert nicht ordnungsgemäß.

Wenn Ihre Erweiterung 15.3 oder höher erfordert, deklarieren Sie die InstallationTarget-Version als [15.0.26730.3, 16.0):

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