Funzione DsGetDcNameA (dsgetdc.h)

La funzione DsGetDcName restituisce il nome di un controller di dominio in un dominio specificato. Questa funzione accetta criteri di selezione aggiuntivi del controller di dominio per indicare la preferenza per un controller di dominio con caratteristiche specifiche.

Sintassi

DSGETDCAPI DWORD DsGetDcNameA(
  [in]  LPCSTR                   ComputerName,
  [in]  LPCSTR                   DomainName,
  [in]  GUID                     *DomainGuid,
  [in]  LPCSTR                   SiteName,
  [in]  ULONG                    Flags,
  [out] PDOMAIN_CONTROLLER_INFOA *DomainControllerInfo
);

Parametri

[in] ComputerName

Puntatore a una stringa con terminazione null che specifica il nome del server per elaborare questa funzione. In genere, questo parametro è NULL, che indica che viene usato il computer locale.

[in] DomainName

Puntatore a una stringa con terminazione null che specifica il nome del dominio o della partizione dell'applicazione da eseguire in query. Questo nome può essere un nome di stile DNS, ad esempio fabrikam.com o un nome in stile flat, ad esempio Fabrikam. Se viene specificato un nome di stile DNS, il nome può essere specificato con o senza un periodo finale.

Se il parametro Flags contiene il flag DS_GC_SERVER_REQUIRED , DomainName deve essere il nome della foresta. In questo caso , DsGetDcName ha esito negativo se DomainName specifica un nome che non è la radice della foresta.

Se il parametro Flags contiene il flag DS_GC_SERVER_REQUIRED e DomainName è NULL, DsGetDcName tenta di trovare un catalogo globale nella foresta del computer identificato da ComputerName, ovvero il computer locale se ComputerName è NULL.

Se DomainName è NULL e il parametro Flags non contiene il flag DS_GC_SERVER_REQUIRED , ComputerName è impostato sul nome di dominio predefinito del dominio primario del computer identificato da ComputerName.

[in] DomainGuid

Puntatore a una struttura GUID che specifica il GUID del dominio sottoposto a query. Se DomainGuid non è NULL e il dominio specificato da DomainName o ComputerName non è disponibile, DsGetDcName tenta di individuare un controller di dominio nel dominio con il GUID specificato da DomainGuid.

[in] SiteName

Puntatore a una stringa con terminazione null che specifica il nome del sito in cui deve esistere fisicamente il controller di dominio restituito. Se questo parametro è NULL, DsGetDcName tenta di restituire un controller di dominio nel sito più vicino al sito del computer specificato da ComputerName. Questo parametro deve essere NULL, per impostazione predefinita.

[in] Flags

Contiene un set di flag che forniscono dati aggiuntivi usati per elaborare la richiesta. Questo parametro può essere una combinazione dei valori seguenti.

DS_AVOID_SELF

Quando viene chiamato da un controller di dominio, specifica che il nome del controller di dominio restituito non deve essere il computer corrente. Se il computer corrente non è un controller di dominio, questo flag viene ignorato. Questo flag può essere usato per ottenere il nome di un altro controller di dominio nel dominio.

DS_BACKGROUND_ONLY

Se il flag DS_FORCE_REDISCOVERY non è specificato, questa funzione usa i dati del controller di dominio memorizzati nella cache. Se i dati memorizzati nella cache sono più di 15 minuti precedenti, la cache viene aggiornata eseguendo il ping del controller di dominio. Se questo flag viene specificato, questo aggiornamento viene evitato anche se i dati memorizzati nella cache sono scaduti. Questo flag deve essere usato se la funzione DsGetDcName viene chiamata periodicamente.

DS_DIRECTORY_SERVICE_PREFERRED

DsGetDcName tenta di trovare un controller di dominio che supporta le funzioni del servizio directory. Se un controller di dominio che supporta i servizi directory non è disponibile, DsGetDcName restituisce il nome di un controller di dominio non del servizio directory. Tuttavia, DsGetDcName restituisce solo un controller di dominio del servizio non directory dopo il tentativo di trovare un controller di dominio del servizio directory timeout.

DS_DIRECTORY_SERVICE_REQUIRED

Richiede che il controller di dominio restituito supporti i servizi directory.

DS_DIRECTORY_SERVICE_6_REQUIRED

Richiede che il controller di dominio restituito sia in esecuzione Windows Server 2008 o versione successiva.

DS_DIRECTORY_SERVICE_8_REQUIRED

Richiede che il controller di dominio restituito sia in esecuzione Windows Server 2012 o versione successiva.

DS_FORCE_REDISCOVERY

Impone l'ignorare i dati del controller di dominio memorizzati nella cache. Quando il flag di DS_FORCE_REDISCOVERY non è specificato, DsGetDcName può restituire i dati del controller di dominio memorizzati nella cache. Se questo flag è specificato, DsGetDcName non userà le informazioni memorizzate nella cache (se presente) ma eseguirà invece un'individuazione del controller di dominio aggiornata.

Questo flag non deve essere usato in condizioni normali, come l'uso delle informazioni sul controller di dominio memorizzato nella cache presenta caratteristiche di prestazioni migliori e consente di garantire che lo stesso controller di dominio venga usato in modo coerente da tutte le applicazioni. Questo flag deve essere usato solo dopo che l'applicazione determina che il controller di dominio restituito da DsGetDcName (quando chiamato senza questo flag) non è accessibile. In tal caso, l'applicazione deve ripetere la chiamata DsGetDcName con questo flag per assicurarsi che le informazioni memorizzate nella cache non utili (se presenti) vengano ignorate e venga individuato un controller di dominio raggiungibile.

DS_GC_SERVER_REQUIRED

Richiede che il controller di dominio restituito sia un server di catalogo globale per l'insieme di domini con il dominio impostato come radice. Se questo flag è impostato e il parametro DomainName non è NULL, DomainName deve specificare un nome di foresta. Questo flag non può essere combinato con i flag DS_PDC_REQUIRED o DS_KDC_REQUIRED .

DS_GOOD_TIMESERV_PREFERRED

DsGetDcName tenta di trovare un controller di dominio che è un server di tempo affidabile. Il servizio ora di Windows può essere configurato per dichiarare uno o più controller di dominio come server di tempo affidabile. Per altre informazioni, vedere la documentazione del servizio ora di Windows . Questo flag deve essere usato solo dal servizio ora di Windows.

DS_IP_REQUIRED

Questo parametro indica che il controller di dominio deve avere un indirizzo IP. In tal caso , DsGetDcName inserisce l'indirizzo del protocollo Internet del controller di dominio nel membro DomainControllerAddress di DomainControllerInfo.

DS_IS_DNS_NAME

Specifica che il parametro DomainName è un nome DNS. Questo flag non può essere combinato con il flag DS_IS_FLAT_NAME .

Specificare DS_IS_DNS_NAME o DS_IS_FLAT_NAME. Se non viene specificato alcun flag, DsGetDcName potrebbe richiedere più tempo per trovare un controller di dominio perché potrebbe dover cercare sia il nome DNS che il nome flat.

DS_IS_FLAT_NAME

Specifica che il parametro DomainName è un nome flat. Questo flag non può essere combinato con il flag DS_IS_DNS_NAME .

DS_KDC_REQUIRED

Richiede che nel controller di dominio restituito sia in esecuzione il servizio Kerberos KDC (Key Distribution Center). Questo flag non può essere combinato con i flag DS_PDC_REQUIRED o DS_GC_SERVER_REQUIRED .

DS_ONLY_LDAP_NEEDED

Specifica che il server restituito è un server LDAP. Il server restituito non è necessariamente un controller di dominio. Nessun altro servizio è implicito essere presente nel server. Il server restituito non ha necessariamente un contenitore di configurazione scrivibile né un contenitore dello schema scrivibile. Il server restituito potrebbe non essere necessariamente usato per creare o modificare i principi di sicurezza. Questo flag può essere usato con il flag DS_GC_SERVER_REQUIRED per restituire un server LDAP che ospita anche un server di catalogo globale. Il server di catalogo globale restituito non è necessariamente un controller di dominio. Nessun altro servizio è implicito essere presente nel server. Se viene specificato questo flag, i flag DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIREDe DS_KDC_REQUIRED flag vengono ignorati.

DS_PDC_REQUIRED

Richiede che il controller di dominio restituito sia quello primario per il dominio. Questo flag non può essere combinato con i flag DS_KDC_REQUIRED o DS_GC_SERVER_REQUIRED .

DS_RETURN_DNS_NAME

Specifica che i nomi restituiti nei membri DomainControllerName e DomainName di DomainControllerInfo devono essere nomi DNS. Se non è disponibile un nome DNS, viene restituito un errore. Questo flag non può essere specificato con il flag di DS_RETURN_FLAT_NAME . Questo flag implica il flag di DS_IP_REQUIRED .

DS_RETURN_FLAT_NAME

Specifica che i nomi restituiti nei membri DomainControllerName e DomainName di DomainControllerInfo devono essere nomi flat. Se un nome flat non è disponibile, viene restituito un errore. Impossibile specificare questo flag con il flag DS_RETURN_DNS_NAME .

DS_TIMESERV_REQUIRED

Richiede che nel controller di dominio restituito sia in esecuzione il servizio Ora di Windows.

DS_TRY_NEXTCLOSEST_SITE

Quando viene specificato questo flag, DsGetDcName tenta di trovare un controller di dominio nello stesso sito del chiamante. Se non viene trovato alcun controller di dominio di questo tipo, troverà un controller di dominio in grado di fornire informazioni sulla topologia e chiamare DsBindToISTG per ottenere un handle di associazione, quindi chiamare DsQuerySitesByCost su UDP per determinare il "sito più vicino successivo" e infine memorizzare nella cache il nome del sito trovato. Se non viene trovato alcun controller di dominio nel sito, DsGetDcName esegue il fallback sul metodo predefinito di individuazione di un controller di dominio.

Se questo flag viene usato insieme a un valore non NULL nel parametro di input SiteName, viene generata ERROR_INVALID_FLAGS .

Inoltre, il tipo di ricerca usato con DS_TRY_NEXT_CLOSEST_SITE è specifico del sito, quindi questo flag viene ignorato se viene usato in combinazione con DS_PDC_REQUIRED. Infine, DS_TRY_NEXTCLOSEST_SITE viene ignorato quando viene usato in combinazione con DS_RETURN_FLAT_NAME perché usa NetBIOS per risolvere il nome, ma il dominio del controller di dominio trovato non corrisponde necessariamente al dominio a cui viene aggiunto il client.

Nota Questo flag è Criteri di gruppo abilitato. Se si abilita l'impostazione dei criteri "Sito più vicino successivo", la posizione successiva del controller di dominio del sito più vicino verrà attivata per il computer in tutte le schede di rete disponibili ma non configurate. Se si disabilita l'impostazione dei criteri, il percorso successivo del controller di dominio del sito più vicino non verrà usato per impostazione predefinita per il computer in tutte le schede di rete disponibili ma non configurate. Tuttavia, se viene eseguita una chiamata del localizzatore di controller di dominio usando il flag di DS_TRY_NEXTCLOSEST_SITE in modo esplicito, DsGetDcName rispetta il comportamento successivo del sito più vicino. Se non si configura questa impostazione di criterio, il percorso successivo del controller di dominio del sito più vicino non verrà usato per impostazione predefinita per il computer in tutte le schede di rete disponibili ma non configurate. Se il flag DS_TRY_NEXTCLOSEST_SITE viene usato in modo esplicito, verrà usato il comportamento successivo del sito più vicino.
 

DS_WRITABLE_REQUIRED

Richiede che il controller di dominio restituito sia scrivibile; ovvero ospitare una copia scrivibile del servizio directory.

DS_WEB_SERVICE_REQUIRED

Richiede che il controller di dominio restituito esegua attualmente il servizio Web Active Directory.

[out] DomainControllerInfo

Puntatore a un valore PDOMAIN_CONTROLLER_INFO che riceve un puntatore a una struttura DOMAIN_CONTROLLER_INFO che contiene dati sul controller di dominio selezionato. Questa struttura viene allocata da DsGetDcName. Il chiamante deve liberare la struttura usando la funzione NetApiBufferFree quando non è più necessaria.

Valore restituito

Se la funzione restituisce dati del controller di dominio, il valore restituito è ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti.

Commenti

La funzione DsGetDcName viene inviata al servizio Netlogon nel computer remoto specificato da ComputerName. Se ComputerName è NULL, la funzione viene elaborata nel computer locale.

DsGetDcName non verifica che il nome del controller di dominio restituito sia il nome di un controller di dominio effettivo o di un catalogo globale. Se è necessaria l'autenticazione reciproca, il chiamante deve eseguire l'autenticazione.

DsGetDcName non richiede alcun accesso specifico al dominio specificato. Per impostazione predefinita, questa funzione non garantisce che il controller di dominio restituito sia attualmente disponibile. Al contrario, il chiamante deve tentare di usare il controller di dominio restituito. Se il controller di dominio non è disponibile, il chiamante deve chiamare di nuovo la funzione DsGetDcName , specificando il flag DS_FORCE_REDISCOVERY .

Tempo di risposta

Quando si usa DsGetDcName , tenere presente i dettagli di intervallo seguenti:
  • DsGetDcName effettua chiamate di rete e può richiedere da alcuni secondi fino a un minuto, a seconda del traffico di rete, della topologia, del carico del controller di dominio e così via.
  • Non è consigliabile chiamare DsGetDcName da un'interfaccia utente o da un altro thread critico di intervallo.
  • Il localizzatore di controller di dominio usa la logica ottimizzata per fornire le informazioni sul controller di dominio il più rapidamente possibile. Usa anche le informazioni memorizzate nella cache nel sito per contattare il controller di dominio più vicino.

Note sulla persistenza del controller di dominio

In Active Directory Domain Services, la funzione del localizzatore di controller di dominio è progettata in modo che dopo che un client trovi un controller di dominio preferito, il client non cercherà un altro a meno che il controller di dominio non risponda o il client venga riavviato. Questa operazione viene definita "Stickiness del controller di dominio". Poiché le workstation funzionano in genere per mesi senza problemi o riavvii, una conseguenza imprevista di questo comportamento è che se un determinato controller di dominio si arresta per la manutenzione, tutti i client connessi a esso spostano le connessioni a un altro controller di dominio. Tuttavia, quando viene eseguito il backup del controller di dominio, nessun client si riconnette a esso perché i client non vengono riavviati molto spesso. Ciò può causare problemi di bilanciamento del carico.

In precedenza, la soluzione più comune a questo problema era distribuire uno script in ogni computer client che periodicamente ha chiamato DsGetDcName usando il DS_FORCE_REDISCOVERY flag . Si tratta di una soluzione piuttosto complessa, quindi Windows Server 2008 e Windows Vista ha introdotto un nuovo meccanismo che ha causato problemi di persistenza del controller di dominio.

Ogni volta che DsGetDcName recupera un nome di controller di dominio dalla cache, verifica se questa voce memorizzata nella cache è scaduta e, in tal caso, rimuove il nome del controller di dominio e tenta di individuare un nome di controller di dominio. L'intervallo di vita di una voce memorizzata nella cache è controllato dal valore nelle chiavi del Registro di sistema seguenti

HKEY_LOCAL_MACHINE\SISTEMA\Currentcontrolset\Servizi\Netlogon\Parametri\ForceRediscoveryInterval

e

HKEY_LOCAL_MACHINE\Software\Politiche\Microsoft\Netlogon\Parametri\ForceRediscoveryInterval

I valori in queste chiavi del Registro di sistema sono di tipo REG_DWORD. Specificano la lunghezza in secondi prima che DsGetDcName tenti di ritrovare il nome del controller di dominio. Il valore predefinito è 43200 secondi (12 ore). Se il valore della voce del Registro di sistema ForceRediscoveryInterval è impostato su 0, il client esegue sempre l'individuazione. Se il valore è impostato su 4294967295, la cache non scade mai e il controller di dominio memorizzato nella cache continua a essere usato. È consigliabile non impostare la voce del Registro di sistema ForceRediscoveryInterval su un valore inferiore a 3600 secondi (60 minuti).

Nota Le impostazioni del Registro di sistema di ForceRediscoveryInterval sono abilitate per i criteri di gruppo. Se si disabilita l'impostazione dei criteri, force rediscovery verrà usato per impostazione predefinita per il computer a intervalli di 12 ore. Se non si configura questa impostazione di criterio, force rediscovery verrà usato per impostazione predefinita per il computer a intervalli di 12 ore, a meno che l'impostazione del computer locale nel Registro di sistema non sia un valore diverso.
 
Si noti che se viene specificato il flag DS_BACKGROUND_ONLY , DsGetDcName non tenterà mai di ritrovare il nome del controller di dominio, poiché il punto di tale flag consiste nel forzare DsGetDcName a usare il nome del controller di dominio memorizzato nella cache anche se è scaduto.

Traccia ETW in DsGetDcName

Per attivare la traccia ETW per DsGetDcName, creare la chiave del Registro di sistema seguente:

HKEY_LOCAL_MACHINE\Sistema\Currentcontrolset\Servizi\DCLocator\Traccia

La chiave avrà una struttura come segue:

String ProcessName
  DWORD  PID <optional>

ProcessName deve essere il nome completo, inclusa l'estensione del processo per cui si desidera ottenere informazioni di traccia. Il PID è obbligatorio solo quando esistono più processi con lo stesso nome. Se è definito, solo il processo con tale PID verrà abilitato per la traccia. Non è possibile tracciare solo 2 processi su 3 (o più) con lo stesso nome. È possibile abilitare un'istanza o tutte le istanze (quando esistono più istanze con lo stesso nome di processo e PID non è specificato, tutte le istanze verranno abilitate per la traccia).

Ad esempio, tracciare tutte le istanze di App1.exe e App2.exe, ma solo l'istanza di App3.exe con pid 999:

App1.exe 
App2.exe
App3.exe
     PID 999

Eseguire il comando seguente per avviare la sessione di traccia:

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

sessionname è il nome specificato per la sessione di traccia. Il GUID per il provider di traccia DCLocator è "cfaa5446-c6c4-4f5c-866f-31c9b55b962d". filename è il nome del file di log in cui vengono scritti gli eventi. traceFlags è uno o più dei flag seguenti che indicano quali aree tracciare:

Contrassegno Valore esadecimale Descrizione
DCLOCATOR_MISC 0x00000002 Debug esterno
DCLOCATOR_MAILSLOT 0x00000010 Messaggi mailslot
DCLOCATOR_SITE 0x00000020 Siti
DCLOCATOR_CRITICAL 0x00000100 Errori importanti
DCLOCATOR_SESSION_SETUP 0x00000200 Manutenzione dominio attendibile
DCLOCATOR_DNS 0x00004000 Registrazione del nome
DCLOCATOR_DNS_MORE 0x00020000 Registrazione dei nomi dettagliata
DCLOCATOR_MAILBOX_TEXT 0x02000000 Messaggi dettagliati delle cassette postali
DCLOCATOR_SITE_MORE 0x08000000 Siti dettagliato
 

Eseguire il comando seguente per arrestare la sessione di traccia:

tracelog.exe -stop <sessionname>

sessionname corrisponde al nome usato all'avvio della sessione.

Nota La chiave del Registro di sistema per il processo di traccia deve essere presente nel Registro di sistema al momento dell'avvio della sessione di traccia. All'avvio della sessione, il processo verificherà se deve generare o meno messaggi di traccia (in base alla presenza o all'assenza di una chiave del Registro di sistema per il nome del processo e il PID facoltativo). Il processo controlla il Registro di sistema solo all'inizio della sessione. Eventuali modifiche apportate al Registro di sistema dopo questa operazione non avranno alcun effetto sulla traccia.
 

Nota

L'intestazione dsgetdc.h definisce DsGetDcName come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito Valore
Client minimo supportato Windows Vista
Server minimo supportato Windows Server 2008
Piattaforma di destinazione Windows
Intestazione dsgetdc.h
Libreria NetApi32.lib
DLL NetApi32.dll

Vedi anche

DOMAIN_CONTROLLER_INFO

Funzioni del servizio directory

DsGetSiteName

DsValidateSubnetName

GUID

NetApiBufferFree

Servizio Ora di Windows