Referenz für SQL Server Express LocalDB: Instanz-APIs

Artikel
05/23/2023

In der herkömmlichen, dienstbasierten SQL Server-Welt sind einzelne auf einem einzelnen Computer installierte SQL Server-Instanzen physisch getrennt. Das heißt, jede Instanz muss separat installiert und entfernt werden, verfügt über einen separaten Satz Binärdateien und wird unter einem separaten Dienstprozess ausgeführt. Der SQL Server-Instanzname wird verwendet, um anzugeben, mit welcher SQL Server-Instanz der Benutzer eine Verbinden herstellen möchte.

Die SQL Server Express LocalDB-Instanz-API verwendet ein vereinfachtes, leichtes Instanzmodell. Obwohl einzelne LocalDB-Instanzen auf dem Datenträger und in der Registrierung getrennt sind, verwenden sie denselben Satz freigegebener LocalDB-Binärdateien. Darüber hinaus verwendet LocalDB keine Dienste. LocalDB-Instanzen werden bei Bedarf durch LocalDB-Instanz-API-Aufrufe gestartet. In LocalDB wird der Instanzname verwendet, um anzugeben, mit welcher LocalDB-Instanz der Benutzer arbeiten will.

Eine LocalDB-Instanz ist immer im Besitz eines einzelnen Benutzers und nur im Kontext dieses Benutzers sichtbar und zugänglich, es sei denn, die Instanzfreigabe ist aktiviert.

Obwohl LocalDB-Instanzen den herkömmlichen SQL Server-Instanzen technisch nicht entsprechen, ist ihre vorgesehene Verwendung ähnlich. Sie werden Instanzen genannt, um diese Ähnlichkeit hervorzuheben und sie für SQL Server Benutzer intuitiver zu machen.

LocalDB unterstützt zwei Arten von Instanzen: automatische Instanzen (AI) und benannte Instanzen (BI). Der Bezeichner für eine LocalDB-Instanz ist der Instanzname.

Automatische LocalDB-Instanzen

Automatische LocalDB-Instanzen sind "öffentlich"; sie werden automatisch für den Benutzer erstellt und verwaltet und können von jeder Anwendung verwendet werden. Eine automatische LocalDB-Instanz ist für jede Version von LocalDB vorhanden, die auf dem Computer des Benutzers installiert ist.

Automatische LocalDB-Instanzen stellen die nahtlose Instanzverwaltung bereit. Der Benutzer muss die Instanz nicht erstellen. Dies ermöglicht Benutzern die einfache Installation von Anwendungen und Migration auf andere Computer. Wenn auf dem Zielcomputer die angegebene Version von LocalDB installiert ist, ist die automatische LocalDB-Instanz für diese Version auch auf diesem Computer verfügbar.

Automatische Instanzverwaltung

Ein Benutzer muss keine automatische LocalDB-Instanz erstellen. Die Instanz wird bei der ersten Verwendung der Instanz lazily erstellt, vorausgesetzt, die angegebene Version von LocalDB ist auf dem Computer des Benutzers verfügbar. Aus Sicht des Benutzers ist die automatische Instanz immer vorhanden, wenn die LocalDB-Binärdateien vorhanden sind.

Andere Instanzverwaltungsvorgänge, z. B. Löschen, Freigabe und Freigabe aufheben, funktionieren auch für automatische Instanzen. Beim Löschen einer automatischen Instanz wird die Instanz effektiv zurückgesetzt, wodurch sie beim nächsten Startvorgang neu erstellt wird. Das Löschen einer automatischen Instanz ist möglicherweise erforderlich, wenn die Systemdatenbanken beschädigt sind.

Benennungsregeln für automatische Instanzen

Automatische LocalDB-Instanzen haben ein besonderes Muster für den Instanznamen, der zu einem reservierten Namespace gehört. Dies ist zur Verhinderung von Namenskonflikten mit benannten LocalDB-Instanzen erforderlich.

Der Name der automatischen Instanz ist die Versionsnummer der LocalDB-Baselineversion, der ein einzelnes "v"-Zeichen vorangestellt ist. Dies sieht wie "v" und zwei Zahlen mit einem Punkt zwischen ihnen aus. Beispielsweise v11.0 oder V12.00.

Beispiele für ungültige automatische Instanznamen sind:

11.0 (das Zeichen "v" am Anfang fehlt)
v11 (Punkt und zweite Zahl der Versionsnummer fehlt)
v11. (zweiten Zahl der Versionsnummer fehlt)
v11.0.1.2 (Versionsnummer besteht aus mehr als zwei Teilen)

Benannte LocalDB-Instanzen

Benannte LocalDB-Instanzen sind "privat"; Eine Instanz gehört einer einzelnen Anwendung, die für das Erstellen und Verwalten der Instanz verantwortlich ist. Benannte LocalDB-Instanzen bieten Isolierung und verbessern die Leistung.

Erstellen einer benannten Instanz

Der Benutzer muss benannte Instanzen explizit über die LocalDB-Verwaltungs-API oder implizit für eine verwaltete Anwendung über die Datei app.config erstellen. Eine verwaltete Anwendung verwendet möglicherweise auch die API.

Jede benannte Instanz verfügt über eine zugeordnete LocalDB-Version. Das heißt, sie verweist auf einen angegebenen Satz LocalDB-Binärdateien. Die Version für die benannte Instanz wird während des Instanzerstellungsprozesses festgelegt.

Benennungsregeln für benannte Instanzen

Ein LocalDB-Instanzname kann insgesamt bis zu 128 Zeichen aufweisen (die Grenze wird durch den Sysname-Datentyp festgelegt). Dies ist ein bedeutender Unterschied im Vergleich zu herkömmlichen SQL Server-Instanznamen, die auf NetBIOS-Namen mit 16 ASCII-Zeichen beschränkt sind. Der Grund für diesen Unterschied ist, dass LocalDB Datenbanken als Dateien behandelt und daher dateibasierte Semantik impliziert, sodass es für Benutzer intuitiv ist, mehr Freiheit bei der Auswahl von Instanznamen zu haben.

Ein LocalDB-Instanzname kann alle Unicode-Zeichen enthalten, die innerhalb der Dateinamenkomponente gültig sind. Unzulässige Zeichen in einer Dateinamenkomponente umfassen im Allgemeinen die folgenden Zeichen: ASCII-/Unicode-Zeichen 1 bis 31 sowie Anführungszeichen (), kleiner als (<), größer als (>), pipe (|), Backspace (\b), tab (\t), Doppelpunkt (:), Sternchen (*), Fragezeichen (?), umgekehrter Schrägstrich (\) und Schrägstrich (/). Beachten Sie, dass das NULL-Zeichen (\0) zugelassen wird, da es zur Zeichenfolgenbeendigung verwendet wird. Alles nach dem ersten NULL-Zeichen wird ignoriert.

Hinweis

Die Liste der ungültigen Zeichen hängt möglicherweise vom Betriebssystem ab und kann sich in zukünftigen Versionen ändern.

Voranstehende und nachfolgende Leerstellen in Instanznamen werden ignoriert und abgeschnitten.

Um Benennungskonflikte zu vermeiden, können benannte LocalDB-Instanzen keinen Namen haben, der dem Benennungsmuster für automatische Instanzen folgt, wie weiter oben in "Automatische Instanzbenennungsregeln" beschrieben. Durch den Versuch, eine benannte Instanz mit einem Namen zu erstellen, der dem automatischen Instanzbenennungsmuster folgt, wird effektiv eine Standardinstanz erstellt.

SQL Server Express LocalDB-Referenzthemen

SQL Server Express LocalDB-Header und Versionsinformationen
Stellt Headerdateiinformationen und Registrierungsschlüssel zum Suchen der LocalDB-Instanz-API bereit.

Verwaltungstool für die Befehlszeile: SqlLocalDB.exe
Beschreibt SqlLocalDB.exe, ein Tool zum Verwalten von LocalDB-Instanzen über die Befehlszeile.

LocalDBCreateInstance-Funktion
Beschreibt die Funktion zum Erstellen einer neuen LocalDB-Instanz.

LocalDBDeleteInstance-Funktion
Beschreibt die Funktion zum Entfernen einer LocalDB-Instanz.

LocalDBFormatMessage-Funktion
Beschreibt die Funktion zum Zurückgeben der lokalisierten Beschreibung für einen LocalDB-Fehler.

LocalDBGetInstanceInfo-Funktion
Beschreibt die Funktion zum Abrufen von Informationen für eine LocalDB-Instanz, wie z. B., ob sie vorhanden ist, Versionsinformationen, ob sie ausgeführt wird usw.

LocalDBGetInstances-Funktion
Beschreibt die Funktion zum Zurückgeben aller LocalDB-Instanzen mit Versionsangabe.

LocalDBGetVersionInfo-Funktion
Beschreibt die Funktion zum Zurückgeben von Informationen für eine angegebene LocalDB-Version.

LocalDBGetVersions-Funktion
Beschreibt die Funktion zum Zurückgeben aller LocalDB-Versionen, die auf einem Computer verfügbar sind.

LocalDBShareInstance-Funktion
Beschreibt die Funktion zum Freigeben einer angegebenen LocalDB-Instanz.

LocalDBStartInstance-Funktion
Beschreibt die Funktion zum Starten einer angegebenen LocalDB-Instanz.

LocalDBStartTracing-Funktion
Beschreibt die Funktion zum Aktivieren der API-Ablaufverfolgung für einen Benutzer.

LocalDBStopInstance-Funktion
Beschreibt die Funktion zum Anhalten der Ausführung einer angegebenen LocalDB-Instanz.

LocalDBStopTracing-Funktion
Beschreibt die Funktion zum Deaktivieren der API-Ablaufverfolgung für einen Benutzer.

LocalDBUnshareInstance-Funktion
Beschreibt die Funktion zum Anhalten der Freigabe einer angegebenen LocalDB-Instanz.