ArbeitsbereicheWorkspaces

Ein Arbeitsbereich ist Darstellungsweise von einer Sammlung von Dateien in Visual Studio "Ordner öffnen", und es wird durch die IWorkspace Typ.A workspace is how Visual Studio represents any collection of files in Open Folder, and it's represented by the IWorkspace type. Selbst nicht der Arbeitsbereich die Inhalte oder Features, die im Zusammenhang mit Dateien im Ordner vertraut machen.By itself, the workspace doesn't understand the contents or features related to files within the folder. Stattdessen bietet es einen allgemeinen Satz von APIs für Funktionen und Erweiterungen erstellen und Nutzen von Daten, denen andere Benutzer darauf reagieren können.Rather, it provides a general set of APIs for features and extensions to produce and consume data that others can act upon. Die Hersteller bestehen über die Managed Extensibility Framework (MEF) mit verschiedenen Attributen exportieren.The producers are composed through the Managed Extensibility Framework (MEF) using various export attributes.

Arbeitsbereich-Anbieter und -DiensteWorkspace providers and services

Arbeitsbereich-Anbieter und -Dienste geben Sie die Daten und Funktionen, auf den Inhalt eines Arbeitsbereichs zu reagieren.Workspace providers and services provide the data and functionality to react to the contents of a workspace. Sie können bieten kontextbezogene Dateiinformationen, Symbole in Quelldateien oder Funktionen zu erstellen.They might provide contextual file information, symbols in source files, or build functionality.

Verwenden Sie die beiden Konzepte eine Factorymuster und über MEF durch den Arbeitsbereich importiert werden.Both concepts use a factory pattern and are imported through MEF by the workspace. Implementieren Sie alle ExportAttribute IProviderMetadataBase oder IWorkspaceServiceFactoryMetadata, aber es gibt konkrete Typen, die Erweiterungen für die exportierten Typen verwendet werden soll.All export attributes implement IProviderMetadataBase or IWorkspaceServiceFactoryMetadata, but there are concrete types that extensions should use for exported types.

Ein Unterschied zwischen Anbietern und -Diensten ist die Beziehung mit dem Arbeitsbereich.One difference between providers and services is their relation to the workspace. Viele Anbieter von einem bestimmten Typ kann über einen Arbeitsbereich verfügen, aber nur ein Dienst von einem bestimmten Typ wird pro Arbeitsbereich erstellt.A workspace can have many providers of a particular type, but only one service of a particular type is created per workspace. Z. B. ein Arbeitsbereich verfügt über viele dateianbieter Scanner, aber der Arbeitsbereich bietet nur einen Indexdienst pro Arbeitsbereich.For example, a workspace has many file scanner providers but the workspace has only one indexing service per workspace.

Ein weiterer wesentlicher Unterschied ist die Nutzung von Daten von Anbietern und -Dienste.Another key difference is consumption of data from providers and services. Der Arbeitsbereich ist der Einstiegspunkt zum Abrufen von Daten von Anbietern Gründen.The workspace is the entry point to get data from providers for a couple reasons. Zuerst müssen die Anbieter in der Regel einige schmalen Satz von Daten, die sie erstellen.First, providers typically have some narrow set of data they create. Die Daten möglicherweise Symbole für eine C# Quelldatei oder erstellen Sie die dateikontexte für einen Datei "cmakelists.txt" Datei.The data might be symbols for a C# source file or build file contexts for a CMakeLists.txt file. Der Arbeitsbereich wird Consumer Anforderung an die Anbieter, deren Metadaten ausrichten, mit der Anforderung, überein.The workspace will match a consumer's request to the providers whose metadata align with the request. Zweitens: Einige Szenarien zu ermöglichen, für viele Anbieter zum mitwirken an den eine Anforderung, während andere Szenarien verwenden Sie den Anbieter mit der höchsten Priorität.Second, some scenarios allow for many providers to contribute to a request while others scenarios use the provider with highest priority.

Im Gegensatz dazu können Erweiterungen Instanzen abgerufen und direkt mit dem Arbeitsbereich-Diensten zu interagieren.In contrast, extensions can get instances of and interact directly with workspace services. Erweiterungsmethoden für IWorkspace stehen für die Dienste, die von Visual Studio bereitgestellt, wie z. B. GetFileWatcherService.Extension methods on IWorkspace are available for the services provided by Visual Studio, such as GetFileWatcherService. Die Erweiterung kann es sich um einen Arbeitsbereich-Dienst für die Komponenten in Ihrer Erweiterung oder für andere Erweiterungen Nutzen bieten.Your extension may offer a workspace service for components within your extension or for other extensions to consume. Consumer verwenden sollten GetServiceAsync oder eine Erweiterungsmethode, die Sie angeben, auf die IWorkspace Typ.Consumers should use GetServiceAsync or an extension method you provide on the IWorkspace type.

Warning

Geschrieben Sie Dienste, die in mit Visual Studio Konflikt nicht werden.Do not author services that conflict with Visual Studio. Es kann zu unerwarteten Problemen führen.It can lead to unexpected issues.

Löschung auf Arbeitsbereich schließenDisposal on workspace closure

Extender möglicherweise auf den Abschluss eines Arbeitsbereichs, dispose, aber aufrufen asynchroner Code.On closure of a workspace, extenders might need to dispose but call asynchronous code. Die IAsyncDisposable Schnittstelle zur Verfügung, um diesen Code einfach ist.The IAsyncDisposable interface is available to make writing this code easy.

ArbeitsbereichseinstellungenWorkspace settings

Arbeitsbereiche umfassen eine IWorkspaceSettingsManager mit einfachen, aber leistungsfähigen Kontrolle über einen Arbeitsbereich.Workspaces have an IWorkspaceSettingsManager service with simple but powerful control over a workspace. Eine grundlegende Übersicht über die Einstellungen finden Sie unter Anpassen von Build- und debugtasks.For a basic overview of settings, see Customize build and debug tasks.

Einstellungen für die meisten SettingsType Typen sind JSON Dateien, z. B. VSWorkspaceSettings.json und "Tasks.VS.JSON".Settings for most SettingsType types are .json files, such as VSWorkspaceSettings.json and tasks.vs.json.

Die Leistungsfähigkeit von arbeitsbereichseinstellungen decken einen "Bereiche", die einfach Pfade innerhalb des Arbeitsbereichs sind.The power of workspace settings centers around "scopes", which are simply paths within the workspace. Wenn ein Consumer aufruft GetAggregatedSettings, werden alle Bereiche, die den angeforderten Pfad und den Typ der Einstellung enthalten aggregiert.When a consumer calls GetAggregatedSettings, all the scopes that include the requested path and type of setting are aggregated. Bereich Aggregation Priorität lautet wie folgt aus:Scope aggregation priority is as follows:

  1. "Lokale Einstellungen" in der Regel dem arbeitsbereichstamm .vs Verzeichnis."Local settings", which is typically the workspace root's .vs directory.
  2. Der angeforderte Pfad selbst.The requested path itself.
  3. Das übergeordnete Verzeichnis der der angeforderte Pfad.The parent directory of the requested path.
  4. Alle übergeordneten Weitere Verzeichnisse bis zur und einschließlich dem arbeitsbereichstamm.All further parent directories up to and including the workspace root.
  5. "Global Settings", die in einem Benutzerverzeichnis ist."Global settings", which is in a user directory.

Das Ergebnis ist eine Instanz der IWorkspaceSettings.The result is an instance of IWorkspaceSettings. Dieses Objekt enthält die Einstellungen für einen bestimmten Typ und kann abgefragt werden, für Schlüsselnamen festlegen, die als gespeicherte string.This object holds the settings for a particular type, and can be queried for setting key names stored as string. Die GetProperty Methoden und WorkspaceSettingsExtensions Erweiterungsmethoden erwarten, dass den Aufrufer den Typ des angeforderten Einstellungswerts kennen.The GetProperty methods and WorkspaceSettingsExtensions extension methods expect the caller to know the type of the setting value being requested. Wie die meisten Einstellungsdateien, als beibehalten werden JSON -Dateien verwenden viele Aufrufe string, bool, int, und Arrays dieser Typen.As most settings files are persisted as .json files, many invocations will use string, bool, int, and arrays of those types. Objekttypen werden ebenfalls unterstützt.Object types are also supported. In diesen Fällen können Sie IWorkspaceSettings selbst als Typargument.In those cases, you can use IWorkspaceSettings itself as the type argument. Zum Beispiel:For example:

{
  "intValue": 1,
  "stringValue": "s",
  "boolValue": true,
  "stringArray": [
    "s1",
    "s2"
  ],
  "nestedIWorkspaceSettings": {
    "nestedString": "ns"
  }
}

Sofern diese Einstellungen wurden in eines vom Benutzers VSWorkspaceSettings.json, die Daten zugegriffen werden können:Assuming these settings were in a user's VSWorkspaceSettings.json, the data can be accessed as:

using System.Collections.Generic;
using Microsoft.VisualStudio.Workspace;
using Microsoft.VisualStudio.Workspace.Settings;

private static void ReadSettings(IWorkspace workspace)
{
    IWorkspaceSettingsManager settingsManager = workspace.GetSettingsManager();
    IWorkspaceSettings settings = settingsManager.GetAggregatedSettings(SettingsTypes.Generic);

    // result == WorkspaceSettingsResult.Success
    WorkspaceSettingsResult result = settings.GetProperty("intValue", out int intValue);
    result = settings.GetProperty("stringValue", out string stringValue);
    result = settings.GetProperty("boolValue", out bool boolValue);
    result = settings.GetProperty("stringArray", out string[] stringArray);
    result = settings.GetProperty("nestedIWorkspaceSettings", out IWorkspaceSettings nestedIWorkspaceSettings);
    result = nestedIWorkspaceSettings.GetProperty("nestedString", out string nestedString);

    // Extension method alternative using default values.
    int intValueOrDefault = settings.Property("intValue", /* default */ 42);

    // Missing key. result == WorkspaceSettingsResult.Undefined
    result = settings.GetProperty("missing", out string missing);

    // Wrong type for a key. result == WorkspaceSettingsResult.Error
    result = settings.GetProperty("intValue", out IWorkspaceSettings notSettings);

    // Special ability to union "stringArray" across all scopes.
    IEnumerable<string> allStringArray = settings.UnionPropertyArray<string>("stringArray");
}

Note

Diese Einstellungen APIs sind unabhängig von den APIs zur Verfügung, in der Microsoft.VisualStudio.Settings Namespace.These settings APIs are unrelated to the APIs available in the Microsoft.VisualStudio.Settings namespace. Arbeitsbereichseinstellungen sind unabhängig von dem Host und Arbeitsbereich spezifische Dateien oder dynamische Einstellungsanbieter verwenden.Workspace settings are agnostic of the host and use workspace-specific settings files or dynamic settings providers.

Bereitstellen von dynamischen-EinstellungenProviding dynamic settings

Extensions bieten IWorkspaceSettingsProviders.Extensions can provide IWorkspaceSettingsProviders. Diese in-Memory-Anbieter können Erweiterungen zum Hinzufügen von Einstellungen oder anderen überschreiben.These in-memory providers allow extensions to add settings or override others.

Exportieren einer IWorkspaceSettingsProvider unterscheidet sich von anderen Anbietern Arbeitsbereich.Exporting an IWorkspaceSettingsProvider is different than other workspace providers. Die Factory ist nicht IWorkspaceProviderFactory und kein besonderes Attribut-Typ vorhanden ist.The factory is not IWorkspaceProviderFactory and there is no special attribute type. Implementieren Sie stattdessen IWorkspaceSettingsProviderFactory und [Export(typeof(IWorkspaceSettingsProviderFactory))].Instead, implement IWorkspaceSettingsProviderFactory and use [Export(typeof(IWorkspaceSettingsProviderFactory))].

// Common workspace provider factory pattern
[ExportFeatureProvider(some, args, to, export)]
internal class MyProviderFactory : IWorkspaceProviderFactory<IFeatureProvider>
{
     IFeatureProvider CreateProvider(IWorkspace workspace) => new Provider(workspace);
}

// IWorkspaceSettingsProvider pattern
[Export(typeof(IWorkspaceSettingsProviderFactory))]
internal class MySettingsProviderFactory : IWorkspaceSettingsProviderFactory
{
    // 100 is typically the value used by built-in settings providers. Lower value is higher priority.
    int Priority => 100;

    IWorkspaceSettingsProvider CreateSettingsProvider(IWorkspace workspace) => new MySettingsProvider(workspace);
}

Tip

Bei der Implementierung von Methoden, die zurückgeben IWorkspaceSettingsSource (z. B. IWorkspaceSettingsProvider.GetSingleSettings), eine Instanz des zurückgeben IWorkspaceSettings statt IWorkspaceSettingsSource.When implementing methods that return IWorkspaceSettingsSource (like IWorkspaceSettingsProvider.GetSingleSettings), return an instance of IWorkspaceSettings rather than IWorkspaceSettingsSource. IWorkspaceSettings enthält weitere Informationen, die bei der einige Einstellungen Aggregationen nützlich sein kann.IWorkspaceSettings provides more information that can be useful during some settings aggregations.

Arbeitsbereich empfohlene VorgehensweisenWorkspace suggested practices

  • Zurückgeben von Objekten aus IWorkspaceProviderFactory.CreateProvider oder ähnliche APIs Denken Sie daran, die ihre Workspace Kontext beim Erstellen.Return objects from IWorkspaceProviderFactory.CreateProvider or similar APIs that remember their Workspace context when created. Anbieter-Schnittstellen wurden erwartet, dass bei der Erstellung dieses Objekts gespeichert wird.Providers interfaces are written expecting this object is kept on creation.
  • Speichern Sie Arbeitsbereich spezifische Caches oder Einstellungen innerhalb der "Lokale Einstellungen"-Pfad des Arbeitsbereichs.Save workspace-specific caches or settings within the "Local settings" path of the workspace. Erstellen Sie einen Pfad für die Datei mit Microsoft.VisualStudio.Workspace.WorkspaceHelper.MakeRootedUnderWorkingFolder in Visual Studio 2017 Version 15.6 oder höher.Create a path for your file using Microsoft.VisualStudio.Workspace.WorkspaceHelper.MakeRootedUnderWorkingFolder in Visual Studio 2017 version 15.6 or later. Verwenden Sie für Versionen vor Version 15.6 den folgenden Codeausschnitt:For versions prior to version 15.6, use the following snippet:
using System.IO;
using Microsoft.VisualStudio.Workspace;
using Microsoft.VisualStudio.Workspace.Settings;

private static string MakeRootedUnderWorkingFolder(IWorkspace workspace, string relativePath)
{
    string workingFolder = workspace.GetSettingsManager().GetAggregatedSettings(SettingsTypes.WorkspaceControlSettings).Property<string>("WorkingFolder");
    return Path.Combine(workingFolder, relativePath);
}

Projektmappen-Ereignissen und das Paket automatisch ladenSolution events and package auto-load

Geladenen Pakete implementieren können IVsSolutionEvents7 , und rufen IVsSolution.AdviseSolutionEvents.Loaded packages can implement IVsSolutionEvents7 and invoke IVsSolution.AdviseSolutionEvents. Es enthält Ereignisse für das Öffnen und schließen einen Ordner in Visual Studio.It includes eventing on opening and closing a folder in Visual Studio.

Ein UI-Kontext kann verwendet werden, um das Paket automatisch laden.A UI context can be used to auto-load your package. Der Wert ist 4646B819-1AE0-4E79-97F4-8A8176FDD664.The value is 4646B819-1AE0-4E79-97F4-8A8176FDD664.

ProblembehandlungTroubleshooting

Das Paket SourceExplorerPackage wurde nicht ordnungsgemäß geladen.The SourceExplorerPackage package did not load correctly

Arbeitsbereich Erweiterbarkeit ist stark MEF-basierte und Komposition Fehler bewirken, dass das Ordner öffnen, um Fehler beim Laden der hosting-Paket.Workspace extensibility is heavily MEF-based, and composition errors will cause the package hosting Open Folder to fail to load. Wenn eine Erweiterung ein Typs mit exportiert z. B. ExportFileContextProviderAttribute, aber der Typ nur implementiert IWorkspaceProviderFactory<IFileContextActionProvider>, wird eine Fehlermeldung beim Versuch, einen Ordner in Visual Studio zu öffnen.For example, if an extension exports a type with ExportFileContextProviderAttribute, but the type only implements IWorkspaceProviderFactory<IFileContextActionProvider>, an error will occur when trying to open a folder in Visual Studio.

Fehlerdetails finden Sie in %LOCALAPPDATA%\Microsoft\VisualStudio\15.0_id\ComponentModelCache\Microsoft.VisualStudio.Default.err.Error details can be found in %LOCALAPPDATA%\Microsoft\VisualStudio\15.0_id\ComponentModelCache\Microsoft.VisualStudio.Default.err. Beheben Sie alle Fehler für Typen bereit, die durch die Erweiterung implementiert.Resolve any errors for types implemented by your extension.

Fehlerdetails finden Sie in %LOCALAPPDATA%\Microsoft\VisualStudio\16.0_id\ComponentModelCache\Microsoft.VisualStudio.Default.err.Error details can be found in %LOCALAPPDATA%\Microsoft\VisualStudio\16.0_id\ComponentModelCache\Microsoft.VisualStudio.Default.err. Beheben Sie alle Fehler für Typen bereit, die durch die Erweiterung implementiert.Resolve any errors for types implemented by your extension.

Nächste SchritteNext steps

  • Datei Kontexten -dateianbieter-Kontext bringen Code Intelligence für Arbeitsbereiche, die "Ordner öffnen".File contexts - File context providers bring code intelligence for Open Folder workspaces.
  • Indizierung -Indizierung Arbeitsbereich erfasst und Informationen zum Arbeitsbereich beibehalten.Indexing - Workspace indexing collects and persists information about the workspace.