DsGetDcNameA-Funktion (dsgetdc.h)
Die DsGetDcName-Funktion gibt den Namen eines Domänencontrollers in einer angegebenen Domäne zurück. Diese Funktion akzeptiert zusätzliche Domänencontrollerauswahlkriterien, um die Präferenz für einen Domänencontroller mit bestimmten Merkmalen anzugeben.
Syntax
DSGETDCAPI DWORD DsGetDcNameA(
[in] LPCSTR ComputerName,
[in] LPCSTR DomainName,
[in] GUID *DomainGuid,
[in] LPCSTR SiteName,
[in] ULONG Flags,
[out] PDOMAIN_CONTROLLER_INFOA *DomainControllerInfo
);
Parameter
[in] ComputerName
Zeiger auf eine NULL-Zeichenfolge, die den Namen des Servers angibt, der diese Funktion verarbeiten soll. In der Regel ist dieser Parameter NULL, was angibt, dass der lokale Computer verwendet wird.
[in] DomainName
Zeiger auf eine NULL-Zeichenfolge, die den Namen der abzufragenden Domäne oder Anwendungspartition angibt. Bei diesem Namen kann es sich entweder um einen DNS-Formatnamen, z. B. fabrikam.com, oder um einen flachen Namen, z. B. Fabrikam, handeln. Wenn ein DNS-Formatvorlagenname angegeben wird, kann der Name mit oder ohne einen nachgestellten Zeitraum angegeben werden.
Wenn der Flags-Parameter das DS_GC_SERVER_REQUIRED-Flag enthält, muss DomainName der Name der Gesamtstruktur sein. In diesem Fall schlägt DsGetDcName fehl, wenn DomainName einen Namen angibt, der nicht dem Gesamtstrukturstamm entspricht.
Wenn der Flags-Parameter das DS_GC_SERVER_REQUIRED-Flag enthält und DomainNameNULL ist, versucht DsGetDcName , einen globalen Katalog in der Gesamtstruktur des Computers zu finden, der durch ComputerName identifiziert wird. Dabei handelt es sich um den lokalen Computer, wenn ComputerNameNULL ist.
Wenn DomainNameNULL ist und der Flags-Parameter nicht das DS_GC_SERVER_REQUIRED-Flag enthält, wird ComputerName auf den Standarddomänennamen der primären Domäne des computers festgelegt, der durch ComputerName identifiziert wird.
[in] DomainGuid
Zeiger auf eine GUID-Struktur , die die GUID der abgefragten Domäne angibt. Wenn DomainGuid nicht NULL ist und die durch DomainName oder ComputerName angegebene Domäne nicht gefunden werden kann, versucht DsGetDcName , einen Domänencontroller in der Domäne zu suchen, in der die von DomainGuid angegebene GUID angegeben ist.
[in] SiteName
Zeiger auf eine null-beendete Zeichenfolge, die den Namen des Standorts angibt, an dem der zurückgegebene Domänencontroller physisch vorhanden sein soll. Wenn dieser Parameter NULL ist, versucht DsGetDcName , einen Domänencontroller am Standort zurückzugeben, der dem Standort des durch ComputerName angegebenen Computers am nächsten kommt. Dieser Parameter sollte standardmäßig NULL sein.
[in] Flags
Enthält eine Reihe von Flags, die zusätzliche Daten bereitstellen, die zum Verarbeiten der Anforderung verwendet werden. Für diesen Parameter ist eine Kombination der folgenden Werte gültig.
DS_AVOID_SELF
Gibt beim Aufruf von einem Domänencontroller an, dass der zurückgegebene Domänencontrollername nicht der aktuelle Computer sein soll. Wenn der aktuelle Computer kein Domänencontroller ist, wird dieses Flag ignoriert. Dieses Flag kann verwendet werden, um den Namen eines anderen Domänencontrollers in der Domäne abzurufen.
DS_BACKGROUND_ONLY
Wenn das DS_FORCE_REDISCOVERY-Flag nicht angegeben ist, verwendet diese Funktion zwischengespeicherte Domänencontrollerdaten. Wenn die zwischengespeicherten Daten mehr als 15 Minuten alt sind, wird der Cache durch Pingen des Domänencontrollers aktualisiert. Wenn dieses Flag angegeben ist, wird diese Aktualisierung auch dann vermieden, wenn die zwischengespeicherten Daten abgelaufen sind. Dieses Flag sollte verwendet werden, wenn die DsGetDcName-Funktion regelmäßig aufgerufen wird.
DS_DIRECTORY_SERVICE_PREFERRED
DsGetDcName versucht, einen Domänencontroller zu finden, der Verzeichnisdienstfunktionen unterstützt. Wenn ein Domänencontroller, der Verzeichnisdienste unterstützt, nicht verfügbar ist, gibt DsGetDcName den Namen eines Nicht-Verzeichnisdienstdomänencontrollers zurück. DsGetDcName gibt jedoch nur einen Nicht-Verzeichnisdienst-Domänencontroller zurück, nachdem beim Versuch, einen Verzeichnisdienstdomänencontroller zu finden, ein Zeitüberschreitung aufgetreten ist.
DS_DIRECTORY_SERVICE_REQUIRED
Erfordert, dass der zurückgegebene Domänencontroller Verzeichnisdienste unterstützt.
DS_DIRECTORY_SERVICE_6_REQUIRED
Erfordert, dass auf dem zurückgegebenen Domänencontroller Windows Server 2008 oder höher ausgeführt wird.
DS_DIRECTORY_SERVICE_8_REQUIRED
Erfordert, dass der zurückgegebene Domänencontroller Windows Server 2012 oder höher ausgeführt wird.
DS_FORCE_REDISCOVERY
Erzwingt, dass zwischengespeicherte Domänencontrollerdaten ignoriert werden. Wenn das DS_FORCE_REDISCOVERY-Flag nicht angegeben wird, gibt DsGetDcName möglicherweise zwischengespeicherte Domänencontrollerdaten zurück. Wenn dieses Flag angegeben ist, verwendet DsGetDcName keine zwischengespeicherten Informationen (sofern vorhanden), sondern führt stattdessen eine ermittlung des neuen Domänencontrollers durch.
Dieses Flag sollte nicht unter normalen Bedingungen verwendet werden, da die Verwendung der zwischengespeicherten Domänencontrollerinformationen bessere Leistungsmerkmale aufweist und sicherstellt, dass derselbe Domänencontroller von allen Anwendungen konsistent verwendet wird. Dieses Flag sollte nur verwendet werden, nachdem die Anwendung festgestellt hat, dass auf den von DsGetDcName zurückgegebenen Domänencontroller (bei Aufruf ohne dieses Flag) nicht zugegriffen werden kann. In diesem Fall sollte die Anwendung den DsGetDcName-Aufruf mit diesem Flag wiederholen, um sicherzustellen, dass die nicht verwendbaren zwischengespeicherten Informationen (falls vorhanden) ignoriert und ein erreichbarer Domänencontroller ermittelt wird.
DS_GC_SERVER_REQUIRED
Erfordert, dass der zurückgegebene Domänencontroller als globaler Katalogserver für die Domänengesamtstruktur fungiert und diese Domäne als Stammdomäne verwendet. Wenn dieses Flag festgelegt ist und der DomainName-Parameter nicht NULL ist, muss DomainName einen Gesamtstrukturnamen angeben. Dieses Flag kann nicht mit den DS_PDC_REQUIRED - oder DS_KDC_REQUIRED-Flags kombiniert werden.
DS_GOOD_TIMESERV_PREFERRED
DsGetDcName versucht, einen Domänencontroller zu finden, der ein zuverlässiger Zeitserver ist. Der Windows-Zeitdienst kann so konfiguriert werden, dass ein oder mehrere Domänencontroller als zuverlässiger Zeitserver deklariert werden. Weitere Informationen finden Sie in der Dokumentation zum Windows-Zeitdienst . Dieses Flag soll nur vom Windows-Zeitdienst verwendet werden.
DS_IP_REQUIRED
Dieser Parameter gibt an, dass der Domänencontroller über eine IP-Adresse verfügen muss. In diesem Fall platziert DsGetDcName die Internetprotokolladresse des Domänencontrollers im DomainControllerAddress-Mitglied von DomainControllerInfo.
DS_IS_DNS_NAME
Gibt an, dass der DomainName-Parameter ein DNS-Name ist. Dieses Flag kann nicht mit dem DS_IS_FLAT_NAME-Flag kombiniert werden.
Geben Sie entweder DS_IS_DNS_NAME oder DS_IS_FLAT_NAME an. Wenn keines der Flags angegeben ist, dauert dsGetDcName möglicherweise länger, um einen Domänencontroller zu finden, da er möglicherweise sowohl nach dem DNS-Format als auch nach dem Flachnamen suchen muss.
DS_IS_FLAT_NAME
Gibt an, dass der DomainName-Parameter ein flacher Name ist. Dieses Flag kann nicht mit dem DS_IS_DNS_NAME-Flag kombiniert werden.
DS_KDC_REQUIRED
Erfordert, dass der zurückgegebene Domänencontroller den Kerberos Key Distribution Center-Dienst ausführt. Dieses Flag kann nicht mit den DS_PDC_REQUIRED - oder DS_GC_SERVER_REQUIRED-Flags kombiniert werden.
DS_ONLY_LDAP_NEEDED
Gibt an, dass der zurückgegebene Server ein LDAP-Server ist. Der zurückgegebene Server ist nicht unbedingt ein Domänencontroller. Es wird davon ausgesehen, dass keine anderen Dienste auf dem Server vorhanden sind. Der zurückgegebene Server verfügt nicht unbedingt über einen beschreibbaren Konfigurationscontainer oder einen beschreibbaren Schemacontainer . Der zurückgegebene Server kann nicht unbedingt zum Erstellen oder Ändern von Sicherheitsprinzipien verwendet werden. Dieses Flag kann mit dem DS_GC_SERVER_REQUIRED-Flag verwendet werden, um einen LDAP-Server zurückzugeben, der auch einen globalen Katalogserver hostet. Der zurückgegebene globale Katalogserver ist nicht unbedingt ein Domänencontroller. Es wird davon ausgesehen, dass keine anderen Dienste auf dem Server vorhanden sind. Wenn dieses Flag angegeben wird, werden die Flags DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIRED und DS_KDC_REQUIRED ignoriert.
DS_PDC_REQUIRED
Erfordert, dass der zurückgegebene Domänencontroller als primärer Domänencontroller für die Domäne fungiert. Dieses Flag kann nicht mit den DS_KDC_REQUIRED - oder DS_GC_SERVER_REQUIRED-Flags kombiniert werden.
DS_RETURN_DNS_NAME
Gibt an, dass die in den Membern DomainControllerName und DomainName von DomainControllerInfo zurückgegebenen Namen DNS-Namen sein sollen. Wenn kein DNS-Name verfügbar ist, wird ein Fehler zurückgegeben. Dieses Flag kann nicht mit dem DS_RETURN_FLAT_NAME-Flag angegeben werden. Dieses Flag impliziert das DS_IP_REQUIRED-Flag .
DS_RETURN_FLAT_NAME
Gibt an, dass die namen, die in den Membern DomainControllerName und DomainName von DomainControllerInfo zurückgegeben werden, Flachnamen sein sollen. Wenn kein flacher Name verfügbar ist, wird ein Fehler zurückgegeben. Dieses Flag kann nicht mit dem DS_RETURN_DNS_NAME-Flag angegeben werden.
DS_TIMESERV_REQUIRED
Erfordert, dass der zurückgegebene Domänencontroller Windows Time Service ausführt.
DS_TRY_NEXTCLOSEST_SITE
Wenn dieses Flag angegeben wird, versucht DsGetDcName , einen Domänencontroller an demselben Standort wie der Aufrufer zu finden. Wenn kein solcher Domänencontroller gefunden wird, wird ein Domänencontroller gefunden, der Topologieinformationen bereitstellen kann, und DsBindToISTG aufruft, um ein Bindungshandle abzurufen, und dann DsQuerySitesByCost über UDP aufrufen, um den "nächsten Standort" zu ermitteln, und schließlich den Namen der gefundenen Website zwischenspeichern. Wenn an diesem Standort kein Domänencontroller gefunden wird, greift DsGetDcName auf die Standardmethode zum Suchen eines Domänencontrollers zurück.
Wenn dieses Flag in Verbindung mit einem Wert ohne NULL im Eingabeparameter SiteName verwendet wird, wird ERROR_INVALID_FLAGS ausgelöst.
Außerdem ist die Art der Suche, die mit DS_TRY_NEXT_CLOSEST_SITE verwendet wird, websitespezifisch, sodass dieses Flag ignoriert wird, wenn es in Verbindung mit DS_PDC_REQUIRED verwendet wird. Schließlich wird DS_TRY_NEXTCLOSEST_SITE ignoriert, wenn sie in Verbindung mit DS_RETURN_FLAT_NAME verwendet wird, da dies NetBIOS verwendet, um den Namen aufzulösen. Die Domäne des gefundenen Domänencontrollers stimmt jedoch nicht unbedingt mit der Domäne überein, der der Client beigetreten ist.
DS_WRITABLE_REQUIRED
Erfordert, dass der zurückgegebene Domänencontroller beschreibbar ist; Das heißt, hosten Sie eine beschreibbare Kopie des Verzeichnisdiensts.
DS_WEB_SERVICE_REQUIRED
Erfordert, dass der zurückgegebene Domänencontroller derzeit den Active Directory-Webdienst ausführt.
[out] DomainControllerInfo
Zeiger auf einen PDOMAIN_CONTROLLER_INFO Wert, der einen Zeiger auf eine DOMAIN_CONTROLLER_INFO Struktur empfängt, die Daten zum ausgewählten Domänencontroller enthält. Diese Struktur wird von DsGetDcName zugeordnet. Der Aufrufer muss die Struktur mithilfe der NetApiBufferFree-Funktion freigeben, wenn sie nicht mehr benötigt wird.
Rückgabewert
Wenn die Funktion Domänencontrollerdaten zurückgibt, wird der Rückgabewert ERROR_SUCCESS.
Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes sein.
Hinweise
Die DsGetDcName-Funktion wird an den Netlogon-Dienst auf dem von ComputerName angegebenen Remotecomputer gesendet. Wenn ComputerNameNULL ist, wird die Funktion auf dem lokalen Computer verarbeitet.
DsGetDcName überprüft nicht, ob der zurückgegebene Domänencontrollername der Name eines tatsächlichen Domänencontrollers oder eines globalen Katalogs ist. Wenn die gegenseitige Authentifizierung erforderlich ist, muss der Aufrufer die Authentifizierung durchführen.
DsGetDcName erfordert keinen bestimmten Zugriff auf die angegebene Domäne. Standardmäßig stellt diese Funktion nicht sicher, dass der zurückgegebene Domänencontroller derzeit verfügbar ist. Stattdessen sollte der Aufrufer versuchen, den zurückgegebenen Domänencontroller zu verwenden. Wenn der Domänencontroller nicht verfügbar ist, sollte der Aufrufer die DsGetDcName-Funktion erneut aufrufen und das flag DS_FORCE_REDISCOVERY angeben.
Antwortzeit
Beachten Sie bei der Verwendung von DsGetDcName die folgenden Zeitplanungsdetails:- DsGetDcName führt Netzwerkaufrufe durch und kann je nach Netzwerkdatenverkehr, Topologie, DC-Auslastung usw. einige Sekunden bis zu einer Minute dauern.
- Es wird NICHT empfohlen , DsGetDcName über eine Benutzeroberfläche oder einen anderen zeitkritischen Thread aufzurufen.
- Der DC Locator verwendet eine optimierte Logik, um die DC-Informationen so schnell wie möglich bereitzustellen. Außerdem werden zwischengespeicherte Informationen am Standort verwendet, um den nächstgelegenen DC zu kontaktieren.
Hinweise zur Domänencontrollerhaftigkeit
In Active Directory Domain Services ist die Domänencontrollerlocatorfunktion so konzipiert, dass der Client nicht nach einem anderen Domänencontroller sucht, sobald ein Client einen bevorzugten Domänencontroller gefunden hat, es sei denn, dieser Domänencontroller reagiert nicht mehr oder der Client wird neu gestartet. Dies wird als "Domänencontroller-Stickiness" bezeichnet. Da Arbeitsstationen in der Regel monatelang ohne Probleme arbeiten oder neu gestartet werden, ist eine unbeabsichtigte Folge dieses Verhaltens, dass alle Clients, die mit diesem verbunden waren, ihre Verbindungen auf einen anderen Domänencontroller verschieben, wenn ein bestimmter Domänencontroller zur Wartung ausfällt. Wenn der Domänencontroller jedoch wieder hochgefahren wird, stellen keine Clients eine Verbindung mit dem Domänencontroller her, da die Clients nicht sehr häufig neu gestartet werden. Dies kann zu Lastenausgleichsproblemen führen.Bisher bestand die häufigste Lösung für dieses Problem darin, ein Skript auf jedem Clientcomputer bereitzustellen, das in regelmäßigen Abständen DsGetDcName mit dem DS_FORCE_REDISCOVERY Flag aufgerufen hat. Dies war eine etwas umständliche Lösung, sodass Windows Server 2008 und Windows Vista einen neuen Mechanismus eingeführt haben, der Probleme mit der Klebigkeit des Domänencontrollers verursachte.
Wenn DsGetDcName einen Domänencontrollernamen aus dem Cache abruft, überprüft es, ob dieser zwischengespeicherte Eintrag abgelaufen ist, und verwirft diesen Domänencontrollernamen und versucht, einen Domänencontrollernamen wiederzuentdecken. Die Lebensdauer eines zwischengespeicherten Eintrags wird durch den Wert in den folgenden Registrierungsschlüsseln gesteuert
HKEY_LOCAL_MACHINE\SYSTEM\Currentcontrolset\Dienstleistungen\Netlogon\Parameter\ForceRediscoveryInterval
und
HKEY_LOCAL_MACHINE\Software\Politik\Microsoft\Netlogon\Parameter\ForceRediscoveryInterval
Die Werte in diesen Registrierungsschlüsseln sind vom Typ REG_DWORD. Sie geben die Länge in Sekunden an , bevor DsGetDcName versuchen soll, den Domänencontrollernamen wiederzuentdecken. Der Standardwert ist 43200 Sekunden (12 Stunden). Wenn der Wert des Registrierungseintrags ForceRediscoveryInterval auf 0 festgelegt ist, führt der Client immer eine Wiederentdeckung durch. Wenn der Wert auf 4294967295 festgelegt ist, läuft der Cache nie ab, und der zwischengespeicherte Domänencontroller wird weiterhin verwendet. Es wird empfohlen, den Registrierungseintrag ForceRediscoveryInterval nicht auf einen Wert festzulegen, der weniger als 3600 Sekunden (60 Minuten) beträgt.
ETW-Ablaufverfolgung in DsGetDcName
Um die ETW-Ablaufverfolgung für DsGetDcName zu aktivieren, erstellen Sie den folgenden Registrierungsschlüssel:HKEY_LOCAL_MACHINE\System\Currentcontrolset\Dienstleistungen\DCLocator\Ablaufverfolgung
Der Schlüssel verfügt wie folgt über eine Struktur:
String ProcessName
DWORD PID <optional>
ProcessName muss der vollständige Name sein, einschließlich der Erweiterung des Prozesses, für den Sie Ablaufverfolgungsinformationen abrufen möchten. PID ist nur erforderlich, wenn mehrere Prozesse mit demselben Namen vorhanden sind. Wenn es definiert ist, wird nur der Prozess mit dieser PID für die Ablaufverfolgung aktiviert. Es ist nicht möglich, nur 2 von 3 (oder mehr) Prozessen mit demselben Namen nachzuverfolgen. Sie können eine instance oder alle Instanzen aktivieren (wenn mehrere Instanzen mit demselben Prozessnamen vorhanden sind und keine PID angegeben ist, werden alle Instanzen für die Ablaufverfolgung aktiviert).
Dies würde beispielsweise alle Instanzen von App1.exe und App2.exe nachverfolgen, jedoch nur die instance von App3.exe, die eine PID von 999 aufweist:
App1.exe
App2.exe
App3.exe
PID 999
Führen Sie den folgenden Befehl aus, um die Ablaufverfolgungssitzung zu starten:
tracelog.exe -start <sessionname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <filename> -flag <traceFlags>
sessionname ist der Name, der für die Ablaufverfolgungssitzung angegeben wird. Die GUId für den DCLocator-Ablaufverfolgungsanbieter lautet "cfaa5446-c6c4-4f5c-866f-31c9b55b962d". filename ist der Name der Protokolldatei, in die die Ereignisse geschrieben werden. traceFlags ist eines oder mehrere der folgenden Flags, die kennzeichnen, welche Bereiche nachverfolgt werden sollen:
| Flag | Hexadezimalwert | BESCHREIBUNG |
|---|---|---|
| DCLOCATOR_MISC | 0x00000002 | Sonstiges Debuggen |
| DCLOCATOR_MAILSLOT | 0x00000010 | Mailslot-Nachrichten |
| DCLOCATOR_SITE | 0x00000020 | Standorte |
| DCLOCATOR_CRITICAL | 0x00000100 | Wichtige Fehler |
| DCLOCATOR_SESSION_SETUP | 0x00000200 | Vertrauenswürdige Domänenwartung |
| DCLOCATOR_DNS | 0x00004000 | Namensregistrierung |
| DCLOCATOR_DNS_MORE | 0x00020000 | Ausführliche Namensregistrierung |
| DCLOCATOR_MAILBOX_TEXT | 0x02000000 | Ausführliche Postfachnachrichten |
| DCLOCATOR_SITE_MORE | 0x08000000 | Ausführliche Websites |
Führen Sie den folgenden Befehl aus, um die Ablaufverfolgungssitzung zu beenden:
tracelog.exe -stop <sessionname>
sessionname ist der gleiche Name wie der Name, den Sie beim Starten der Sitzung verwendet haben.
Hinweis
Der Dsgetdc.h-Header definiert DsGetDcName als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista |
| Unterstützte Mindestversion (Server) | Windows Server 2008 |
| Zielplattform | Windows |
| Kopfzeile | dsgetdc.h |
| Bibliothek | NetApi32.lib |
| DLL | NetApi32.dll |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für