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

Zeigen Sie auf eine mit Null beendete Zeichenfolge, die den Namen des Servers angibt, der diese Funktion verarbeitet. In der Regel ist dieser Parameter NULL-, was angibt, dass der lokale Computer verwendet wird.

[in] DomainName

Zeigen Sie auf eine mit Null beendete Zeichenfolge, die den Namen der zu abfragenden Domäne oder Anwendungspartition angibt. Dieser Name kann z. B. ein DNS-Formatvorlagenname sein, z. B. fabrikam.com oder ein flacher Name, z. B. Fabrikam. Wenn ein DNS-Formatvorlagenname angegeben wird, kann der Name mit oder ohne nachfolgende Periode angegeben werden.

Wenn der parameter Flags 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 der Gesamtstrukturstamm ist.

Wenn der parameter Flags 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 ComputerNameidentifiziert wird. Dies ist der lokale Computer, wenn ComputerNameNULList.

Wenn DomainName-NULL- ist und der parameter Flags 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 ComputerNameidentifiziert 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, der die GUID durch DomainGuidangegeben hat.

[in] SiteName

Zeigen Sie auf eine mit 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 am nächsten ist, der durch ComputerNameangegeben wird. 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. Dieser Parameter kann eine Kombination aus den folgenden Werten sein.

DS_AVOID_SELF

Wenn sie von einem Domänencontroller aufgerufen wird, wird angegeben, 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-Verzeichnisdienst-Domänencontrollers zurück. DsGetDcName gibt jedoch nur einen Domänencontroller ohne Verzeichnisdienst zurück, nachdem versucht wurde, einen Domänencontroller des Verzeichnisdiensts zu finden.

DS_DIRECTORY_SERVICE_REQUIRED

Erfordert, dass der zurückgegebene Domänencontroller Verzeichnisdienste unterstützt.

DS_DIRECTORY_SERVICE_6_REQUIRED

Erfordert, dass der zurückgegebene Domänencontroller Windows Server 2008 oder höher ausführt.

DS_DIRECTORY_SERVICE_8_REQUIRED

Erfordert, dass der zurückgegebene Domänencontroller Windows Server 2012 oder höher ausführt.

DS_FORCE_REDISCOVERY

Erzwingt, dass zwischengespeicherte Domänencontrollerdaten ignoriert werden. Wenn das DS_FORCE_REDISCOVERY Flag nicht angegeben ist, können DsGetDcName- zwischengespeicherte Domänencontrollerdaten zurückgeben. Wenn dieses Flag angegeben ist, verwendet dsGetDcName keine zwischengespeicherten Informationen (sofern vorhanden), sondern führt stattdessen eine neue Domänencontrollerermittlung durch.

Dieses Flag sollte nicht unter normalen Bedingungen verwendet werden, da die Verwendung der zwischengespeicherten Domänencontrollerinformationen bessere Leistungsmerkmale aufweist und hilft sicherzustellen, dass derselbe Domänencontroller konsistent von allen Anwendungen verwendet wird. Dieses Flag sollte nur verwendet werden, nachdem die Anwendung bestimmt hat, dass der von DsGetDcName zurückgegebene Domänencontroller (wenn ohne dieses Flag aufgerufen) nicht zugänglich ist. In diesem Fall sollte die Anwendung den DsGetDcName Aufruf mit diesem Flag wiederholen, um sicherzustellen, dass die nicht zu verwendenden zwischengespeicherten Informationen (falls vorhanden) ignoriert und ein erreichbarer Domänencontroller erkannt wird.

DS_GC_SERVER_REQUIRED

Erfordert, dass der zurückgegebene Domänencontroller ein globaler Katalogserver für die Gesamtstruktur von Domänen mit dieser Domäne als Stamm ist. Wenn dieses Flag festgelegt ist und der parameter DomainName nicht NULList, muss DomainName einen Gesamtstrukturnamen angeben. Diese Kennzeichnung 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 Windows Time Service. Dieses Kennzeichen 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. Diese Kennzeichnung kann nicht mit der DS_IS_FLAT_NAME-Kennzeichnung kombiniert werden.

Geben Sie entweder DS_IS_DNS_NAME oder DS_IS_FLAT_NAMEan. Wenn keines der Kennzeichnungen angegeben ist, dauert DsGetDcName- möglicherweise länger, um einen Domänencontroller zu finden, da er möglicherweise sowohl nach dem DNS-Stil als auch nach dem flachen Namen suchen muss.

DS_IS_FLAT_NAME

Gibt an, dass der parameter DomainName ein flacher Name ist. Dieses Kennzeichen kann nicht mit der DS_IS_DNS_NAME-Kennzeichnung kombiniert werden.

DS_KDC_REQUIRED

Erfordert, dass der zurückgegebene Domänencontroller derzeit den Kerberos-Schlüsselverteilungscenter-Dienst ausführt. Diese Kennzeichnung 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 werden keine anderen Dienste impliziert, die auf dem Server vorhanden sind. Der zurückgegebene Server verfügt nicht unbedingt über einen schreibbaren Konfigurationscontainer Container oder einen schreibbaren Schemacontainer Container. Der zurückgegebene Server wird möglicherweise nicht unbedingt verwendet, um Sicherheitsprinzipien zu erstellen oder zu ändern. Dieses Flag kann mit dem flag DS_GC_SERVER_REQUIRED verwendet werden, um einen LDAP-Server zurückzugeben, der auch einen globalen Katalogserver hostt. Der zurückgegebene globale Katalogserver ist nicht unbedingt ein Domänencontroller. Es werden keine anderen Dienste impliziert, die auf dem Server vorhanden sind. Wenn diese Kennzeichnung angegeben ist, werden die DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIREDund DS_KDC_REQUIRED Flags ignoriert.

DS_PDC_REQUIRED

Erfordert, dass der zurückgegebene Domänencontroller der primäre Domänencontroller für die Domäne ist. Diese Kennzeichnung kann nicht mit den DS_KDC_REQUIRED- oder DS_GC_SERVER_REQUIRED Flags kombiniert werden.

DS_RETURN_DNS_NAME

Gibt an, dass die im DomainControllerName- zurückgegebenen Namen und DomainName Mitglieder von DomainControllerInfo- 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. Diese Kennzeichnung impliziert die DS_IP_REQUIRED Kennzeichnung.

DS_RETURN_FLAT_NAME

Gibt an, dass die im DomainControllerName- zurückgegebenen Namen und DomainName Mitglieder von DomainControllerInfo- flache Namen sein sollen. Wenn kein Flachname 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 derzeit den Windows-Zeitdienst ausführt.

DS_TRY_NEXTCLOSEST_SITE

Wenn dieses Flag angegeben wird, DsGetDcName versucht, einen Domänencontroller an derselben Website wie der Aufrufer zu finden. Wenn kein solcher Domänencontroller gefunden wird, wird ein Domänencontroller gefunden, der Topologieinformationen bereitstellen und DsBindToISTG- aufrufen kann, um ein Bindungshandle abzurufen, und rufen Sie dann DsQuerySitesByCost über UDP auf, um den "nächsten nächstgelegenen Standort" zu ermitteln, und schließlich den Namen der gefundenen Website zwischenspeichern. Wenn kein Domänencontroller an diesem Standort gefunden wird, greift DsGetDcName auf die Standardmethode zum Auffinden eines Domänencontrollers zurück.

Wenn dieses Flag in Verbindung mit einem Wert ungleich NULL im Eingabeparameter SiteNameverwendet 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_REQUIREDverwendet wird. Schließlich wird DS_TRY_NEXTCLOSEST_SITE ignoriert, wenn sie in Verbindung mit DS_RETURN_FLAT_NAME verwendet wird, da netBIOS verwendet wird, um den Namen aufzulösen, aber die Domäne des gefundenen Domänencontrollers stimmt nicht unbedingt mit der Domäne überein, der der Client beigetreten ist.

DS_WRITABLE_REQUIRED

Erfordert, dass der zurückgegebene Domänencontroller schreibbar ist; d. h. hosten Sie eine schreibbare Kopie des Verzeichnisdiensts.

DS_WEB_SERVICE_REQUIRED

Erfordert, dass der zurückgegebene Domänencontroller derzeit den Active Directory-Webdienst ausführt.

[out] DomainControllerInfo

Zeigen Sie 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 DsGetDcNamezugeordnet. Der Aufrufer muss die Struktur mithilfe der NetApiBufferFree Funktion freigeben, wenn sie nicht mehr erforderlich ist.

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.

Bemerkungen

Die DsGetDcName--Funktion wird an den Netlogon-Dienst auf dem Remotecomputer gesendet, der von ComputerNameangegeben wird. Wenn ComputerName-NULL-ist, wird die Funktion auf dem lokalen Computer verarbeitet.

DsGetDcName nicht überprüft, ob der zurückgegebene Domänencontrollername der Name eines tatsächlichen Domänencontrollers oder eines globalen Katalogs ist. Wenn eine gegenseitige Authentifizierung erforderlich ist, muss der Aufrufer die Authentifizierung ausfü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 DS_FORCE_REDISCOVERY Flag angeben.

Antwortzeit

Beachten Sie bei der Verwendung von DsGetDcName die folgenden Anzeigedauerdetails:

• DsGetDcName Netzwerkaufrufe tätigt und kann je nach Netzwerkdatenverkehr, Topologie, DC-Last usw. einige Sekunden dauern.
• Es wird NICHT empfohlen, DsGetDcName- von einer Benutzeroberfläche oder einem anderen wichtigen Timing-Thread aufzurufen.
• Der DC Locator verwendet 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änencontroller-Stickiness

In Active Directory Domain Services ist die Domänencontroller-Locator-Funktion so konzipiert, dass der Client nach einem bevorzugten Domänencontroller nicht mehr sucht, es sei denn, der 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 Problem oder Neustart funktionieren, besteht eine unbeabsichtigte Folge dieses Verhaltens darin, dass alle Clients, die mit ihr verbunden waren, zur Wartung heruntergefahren werden, alle Clients, die mit ihr verbunden waren, auf einen anderen Domänencontroller verschieben. Wenn der Domänencontroller jedoch wieder gestartet wird, stellen keine Clients jemals wieder eine Verbindung mit dem Domänencontroller her, da die Clients nicht sehr häufig neu gestartet werden. Dies kann zu Lastenausgleichsproblemen führen.

Bisher war die häufigste Lösung für dieses Problem die Bereitstellung eines Skripts auf jedem Clientcomputer, das regelmäßig DsGetDcName unter Verwendung des DS_FORCE_REDISCOVERY-Flags aufgerufen hat. Dies war eine etwas mühsame Lösung, sodass Windows Server 2008 und Windows Vista einen neuen Mechanismus eingeführt haben, der Probleme mit der Domänencontroller-Stickigkeit verursachte.

Wenn DsGetDcName einen Domänencontrollernamen aus dem Cache abruft, überprüft er, ob dieser zwischengespeicherte Eintrag abgelaufen ist, und verwirft in diesem Fall 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\Services\Netlogon\Parameter\ForceRediscoveryInterval

und

HKEY_LOCAL_MACHINE\Software-\-Richtlinien\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 sollte, den Domänencontrollernamen wiederzuentdecken. Der Standardwert ist 43200 Sekunden (12 Stunden). Wenn der Wert des ForceRediscoveryInterval Registrierungseintrag auf 0 festgelegt ist, führt der Client immer wiederentdeckt. 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 ForceRediscoveryInterval Registrierungseintrag nicht auf einen Wert festzulegen, der kleiner als 3600 Sekunden ist (60 Minuten).

Beachten Sie, dass DS_BACKGROUND_ONLYDsGetDcName- niemals versucht, den Domänencontrollernamen wiederzuentdecken, da der Punkt dieses Flags DsGetDcName erzwingt, den namen des zwischengespeicherten Domänencontrollers zu verwenden, auch wenn es abgelaufen ist.

ETW-Ablaufverfolgung in DsGetDcName

Um ETW-Ablaufverfolgungs- für DsGetDcNamezu aktivieren, erstellen Sie den folgenden Registrierungsschlüssel:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\DCLocator\Ablaufverfolgung

Der Schlüssel hat eine Struktur wie folgt:

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 sie 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 Instanz oder alle Instanzen aktivieren (wenn mehrere Instanzen mit demselben Prozessnamen vorhanden sind und PID nicht angegeben ist, werden alle Instanzen für die Ablaufverfolgung aktiviert).

Dies würde beispielsweise alle Instanzen von App1.exe und App2.exenachverfolgen, aber nur die Instanz von App3.exe, die eine PID von 999 hat:

App1.exe 
App2.exe
App3.exe
     PID 999

Führen Sie den folgenden Befehl aus, um die Ablaufverfolgungssitzung zu starten:

tracelog.exe -start <Sitzungsname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <Dateinamen> -flag <traceFlags>

Sitzungsname ist der Name der Ablaufverfolgungssitzung. Die guid für den DCLocator-Ablaufverfolgungsanbieter lautet "cfaa5446-c6c4-4f5c-866f-31c9b55b962d". Dateinamen ist der Name der Protokolldatei, in die die Ereignisse geschrieben werden. traceFlags ist eine oder mehrere der folgenden Flags, die bedeuten, welche Bereiche nachverfolgt werden sollen:

Flagge	Hexwert	Beschreibung
DCLOCATOR_MISC	0x00000002	Verschiedenes Debuggen
DCLOCATOR_MAILSLOT	0x00000010	E-Mail-Nachrichten
DCLOCATOR_SITE	0x00000020	Lagen
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 <Sitzungsname>

Sitzungsname ist derselbe Name wie der Name, den Sie beim Starten der Sitzung verwendet haben.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista
mindestens unterstützte Server-	Windows Server 2008
Zielplattform-	Fenster
Header-	dsgetdc.h
Library	NetApi32.lib
DLL-	NetApi32.dll

Siehe auch

DOMAIN_CONTROLLER_INFO

Verzeichnisdienstfunktionen

DsGetSiteName-

DsValidateSubnetName

GUID-

NetApiBufferFree-

Windows-Zeitdienst-