Erweitern von Visual Studio-Dokumenten

Ein Dokument ist die Speicherdarstellung einer Datei, die in Visual Studio geöffnet wird. Sie wird von moniker genannt, was eine absolute Uri Verwendung des file:// Schemas ist. Ein Dokument wird durch die DocumentSnapshot Klasse dargestellt, die die folgenden Eigenschaften aufweist:

• Moniker
• IsDirty
• IsReadOnly
• IsInitialized

Das DocumentsExtensibility Objekt stellt verschiedene Methoden bereit, die zum Abrufen und Arbeiten mit DocumentSnapshot Objektinstanzen verwendet werden.

Arbeiten mit Dokumenten

Dieses Handbuch wurde entwickelt, um die wichtigsten Benutzerszenarien beim Arbeiten mit Dokumenten abzudecken:

• Öffnen eines Dokuments
• Abrufen eines Textdokuments Momentaufnahme
• Reagieren auf Ereignisse im Zusammenhang mit Dokumenten

Öffnen eines Dokuments

Angesichts des Pfads zu einer Datei auf dem Datenträger ist es einfach, die Datei in Visual Studio zu öffnen:

DocumentsExtensibility documents = this.Extensibility.Documents();

Uri uri = new Uri(@"C:\path\to\Class1.cs", UriKind.Absolute);
DocumentSnapshot document = await documents.OpenDocumentAsync(uri, cancellationToken);

// optionally do something with the document

Abrufen eines Textdokuments Momentaufnahme

A DocumentSnapshot ist eine abstrakte Darstellung eines Dokuments. Wenn Sie den Text in einer DocumentSnapshotZeichenfolge lesen oder schreiben möchten, können Sie dies über die ITextDocumentSnapshot Schnittstelle tun, die mit der AsTextDocumentAsync Erweiterungsmethode abgerufen DocumentSnapshotwerden kann.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    DocumentsExtensibility documents = this.Extensibility.Documents();

    Uri moniker = await context.GetSelectedPathAsync(cancellationToken);
    DocumentSnapshot document = await documents.GetDocumentAsync(moniker, cancellationToken);
    ITextDocumentSnapshot snapshot = await document.AsTextDocumentAsync(this.Extensibility, cancellationToken);

    // insert the current date/time
    EditorExtensibility editor = this.Extensibility.Editor();
    using ITextViewSnapshot textView = await context.GetActiveTextViewAsync(cancellationToken);

    await editor.EditAsync(
        batch => snapshot.AsEditable(batch).Replace(textView.Selection.Extent, DateTime.Now.ToString()),
        cancellationToken);
}

Reagieren auf Ereignisse im Zusammenhang mit Dokumenten

Es gibt Szenarien, in denen Komponenten auf Ereignisse im Zusammenhang mit Dokumenten reagieren möchten (d. a. wenn sie geöffnet, geschlossen oder gespeichert werden). Dazu können Sie die IDocumentEventsListener Schnittstelle implementieren und DocumentsExtensibility.SubscribeAsync das Ereignisabonnement einrichten.

internal sealed class SubscribeCommand : Command, IToggleCommand
{
    private IDisposable? subscription;

    bool? IToggleCommand.IsChecked => this.subscription is not null;

    public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        if (this.subscription is null)
        {
            // subscribe for events
            this.subscription = await Subscription.CreateInstanceAsync(this.Extensibility, cancellationToken);
        }
        else
        {
            // remove the event subscription
            this.subscription.Dispose();
            this.subscription = null;
        }

        this.OnPropertyChanged(new PropertyChangedEventArgs(nameof(IToggleCommand.IsChecked)));
    }

    private class Subscription : IDisposable, IDocumentEventsListener
    {
        private readonly OutputWindowExtensibility output;
        private IDisposable? rawSubscription;

        private Subscription(VisualStudioExtensibility extensibility)
        {
            this.output = extensibility.Views().Output;
        }

        public static async Task<Subscription> CreateInstanceAsync(
            VisualStudioExtensibility extensibility,
            CancellationToken cancellationToken)
        {
            var subscription = new Subscription(extensibility);

            DocumentsExtensibility documents = extensibility.Documents();
            subscription.rawSubscription = await documents.SubscribeAsync(subscription, filterRegex: null, cancellationToken);

            return subscription;
        }

        public void Dispose()
        {
            this.rawSubscription?.Dispose();
            this.rawSubscription = null;
        }

        Task IDocumentEventsListener.ClosedAsync(DocumentEventArgs e, CancellationToken token)
        {
            string text = $"IDocumentEventsListener.ClosedAsync ({e.Moniker})";
            return this.OutputEventTextAsync(text, token);
        }

        Task IDocumentEventsListener.HiddenAsync(DocumentEventArgs e, CancellationToken token)
        {
            string text = $"IDocumentEventsListener.HiddenAsync ({e.Moniker})";
            return this.OutputEventTextAsync(text, token);
        }

        Task IDocumentEventsListener.OpenedAsync(DocumentEventArgs e, CancellationToken token)
        {
            string text = $"IDocumentEventsListener.OpenedAsync ({e.Moniker})";
            return this.OutputEventTextAsync(text, token);
        }

        Task IDocumentEventsListener.RenamedAsync(RenamedDocumentEventArgs e, CancellationToken token)
        {
            string text = $"IDocumentEventsListener.RenamedAsync ({e.OldMoniker} -> {e.Moniker})";
            return this.OutputEventTextAsync(text, token);
        }

        Task IDocumentEventsListener.SavedAsync(DocumentEventArgs e, CancellationToken token)
        {
            string text = $"IDocumentEventsListener.SavedAsync ({e.Moniker})";
            return this.OutputEventTextAsync(text, token);
        }

        Task IDocumentEventsListener.SavingAsync(DocumentEventArgs e, CancellationToken token)
        {
            string text = $"IDocumentEventsListener.SavingAsync ({e.Moniker})";
            return this.OutputEventTextAsync(text, token);
        }

        Task IDocumentEventsListener.ShownAsync(DocumentEventArgs e, CancellationToken token)
        {
            string text = $"IDocumentEventsListener.ShownAsync ({e.Moniker})";
            return this.OutputEventTextAsync(text, token);
        }

        private async Task OutputEventTextAsync(string text, CancellationToken token)
        {
            using OutputWindow outputWindow = await this.output.GetChannelAsync(
                identifier: "Document Sample Command Output",
                displayNameResourceId: nameof(Strings.DocumentsSampleOutputWindowPaneName),
                token);

            await outputWindow.Writer.WriteLineAsync($"Event received: {text}");
        }
    }
}

Nächste Schritte

• Folgen Sie der Schnellstartanleitung zum Erstellen des Projekts im Abschnitt "Erste Schritte".