public override ImmutableArray<PortableExecutableReference> ResolveReference(string reference, string baseFilePath, MetadataReferenceProperties properties)
        {
            Dictionary<string, PortableExecutableReference> map;

            if (PathUtilities.IsFilePath(reference))
            {
                if (_pathResolver != null)
                {
                    reference = _pathResolver.ResolvePath(reference, baseFilePath);
                    if (reference == null)
                    {
                        return ImmutableArray<PortableExecutableReference>.Empty;
                    }
                }

                map = _files;
            }
            else
            {
                map = _assemblyNames;
            }

            PortableExecutableReference result;
            return map.TryGetValue(reference, out result) ? ImmutableArray.Create(result) : ImmutableArray<PortableExecutableReference>.Empty;
        }

        internal Metadata GetMetadata(string fullPath, MetadataReferenceProperties properties)
        {
            // Check if we have an entry in the dictionary.
            FileKey? fileKey = GetUniqueFileKey(fullPath);

            Metadata metadata;
            if (fileKey.HasValue && metadataCache.TryGetValue(fileKey.Value, out metadata) && metadata != null)
            {
                CompilerServerLogger.Log("Using already loaded metadata for assembly reference '{0}'", fileKey);
                return metadata;
            }

            if (properties.Kind == MetadataImageKind.Module)
            {
                var result = CreateModuleMetadata(fullPath, prefetchEntireImage: true);
                //?? never add modules to cache?
                return result;
            }
            else
            {
                var primaryModule = CreateModuleMetadata(fullPath, prefetchEntireImage: false);

                // Get all the modules, and load them. Create an assembly metadata.
                var allModules = GetAllModules(primaryModule, Path.GetDirectoryName(fullPath));
                Metadata result = AssemblyMetadata.Create(allModules);

                result = metadataCache.GetOrAdd(fileKey.Value, result);

                return result;
            }
        }

            public MetadataReference GetAddOrUpdate(string path, MetadataReferenceProperties properties)
            {
                using (_gate.DisposableWait())
                {
                    WeakReference<MetadataReference> weakref;
                    MetadataReference mref = null;

                    if (!(_references.TryGetValue(properties, out weakref) && weakref.TryGetTarget(out mref)))
                    {
                        // try to base this metadata reference off of an existing one, so we don't load the metadata bytes twice.
                        foreach (var wr in _references.Values)
                        {
                            if (wr.TryGetTarget(out mref))
                            {
                                mref = mref.WithProperties(properties);
                                break;
                            }
                        }

                        if (mref == null)
                        {
                            mref = _cache._createReference(path, properties);
                        }

                        _references[properties] = new WeakReference<MetadataReference>(mref);
                    }

                    return mref;
                }
            }

 public MetadataFileReference(string fullPath, MetadataReferenceProperties properties, DocumentationProvider documentation = null)
     : base(properties, fullPath, initialDocumentation: documentation ?? DocumentationProvider.Default)
 {
     if (fullPath == null)
     {
         throw new ArgumentNullException("fullPath");
     }
 }

            public ShadowCopyReference(MetadataShadowCopyProvider provider, string originalPath, MetadataReferenceProperties properties)
                : base(properties, originalPath)
            {
                Debug.Assert(originalPath != null);
                Debug.Assert(provider != null);

                _provider = provider;
            }

        public MetadataReference GetReference(string path, MetadataReferenceProperties properties)
        {
            if (!_referenceSets.TryGetValue(path, out var referenceSet))
            {
                referenceSet = ImmutableInterlocked.GetOrAdd(ref _referenceSets, path, new ReferenceSet(this));
            }

            return referenceSet.GetAddOrUpdate(path, properties);
        }

        /// <summary>
        /// Returns an instance of the reference with specified properties, or this instance if properties haven't changed.
        /// </summary>
        /// <param name="properties">The new properties for the reference.</param>
        /// <exception cref="ArgumentException">Specified values not valid for this reference.</exception>
        public MetadataReference WithProperties(MetadataReferenceProperties properties)
        {
            if (properties == this.Properties)
            {
                return this;
            }

            return WithPropertiesImplReturningMetadataReference(properties);
        }

 protected PortableExecutableReference(
     MetadataReferenceProperties properties,
     string fullPath = null,
     DocumentationProvider initialDocumentation = null)
     : base(properties)
 {
     _filePath = fullPath;
     _lazyDocumentation = initialDocumentation;
 }

 protected override PortableExecutableReference WithPropertiesImpl(MetadataReferenceProperties properties)
 {
     return new MetadataImageReference(
         _metadata,
         properties,
         this.DocumentationProvider,
         this.FilePath,
         _display);
 }

        public override ImmutableArray<PortableExecutableReference> ResolveReference(string reference, string baseFilePath, MetadataReferenceProperties properties)
        {
            var path = PathResolver.ResolveReference(reference, baseFilePath);
            if (path == null)
            {
                return ImmutableArray<PortableExecutableReference>.Empty;
            }

            return ImmutableArray.Create(Provider.GetReference(path, properties));
        }

            public override PortableExecutableReference GetReference(string fullPath, MetadataReferenceProperties properties = default(MetadataReferenceProperties))
            {
                AssemblyMetadata metadata;
                if (_cache.TryGetValue(fullPath, out metadata))
                {
                    return metadata.GetReference(MakeDocumentationProvider());
                }

                _cache.Add(fullPath, metadata = AssemblyMetadata.CreateFromFile(fullPath));
                return metadata.GetReference(MakeDocumentationProvider());
            }

        public override ImmutableArray<PortableExecutableReference> ResolveReference(string reference, string baseFilePath, MetadataReferenceProperties properties)
        {
            // Note: currently not handling relative paths, since we don't have tests that use them

            if (File.Exists(reference))
            {
                return ImmutableArray.Create(MetadataReference.CreateFromFile(reference, properties));
            }

            return default(ImmutableArray<PortableExecutableReference>);
        }

 public void AddProjectReference(IProjectContext project, MetadataReferenceProperties properties)
 {
     // AbstractProject and ProjectTracker track project references using the project bin output path.
     // Setting the command line arguments should have already set the output file name and folder.
     // We fetch this output path to add the reference.
     var referencedProject = this.ProjectTracker.GetProject(project.Id);
     var binPathOpt = referencedProject.TryGetBinOutputPath();
     if (!string.IsNullOrEmpty(binPathOpt))
     {
         AddMetadataReferenceAndTryConvertingToProjectReferenceIfPossible(binPathOpt, properties);
     }
 }

        /// <summary>
        /// Returns an instance of the reference with specified properties, or this instance if properties haven't changed.
        /// </summary>
        /// <param name="properties">The new properties for the reference.</param>
        /// <exception cref="ArgumentException">Specified values not valid for this reference.</exception> 
        public new CompilationReference WithProperties(MetadataReferenceProperties properties)
        {
            if (properties == this.Properties)
            {
                return this;
            }

            if (properties.Kind == MetadataImageKind.Module)
            {
                throw new ArgumentException(CodeAnalysisResources.CannotCreateReferenceToModule);
            }

            return WithPropertiesImpl(properties);
        }

        public void WithXxx()
        {
            var p = new MetadataReferenceProperties(MetadataImageKind.Assembly, ImmutableArray.Create("a"), embedInteropTypes: false);

            Assert.Equal(p.WithAliases(null), new MetadataReferenceProperties(MetadataImageKind.Assembly, ImmutableArray<string>.Empty, embedInteropTypes: false));
            Assert.Equal(p.WithAliases(default(ImmutableArray<string>)), new MetadataReferenceProperties(MetadataImageKind.Assembly, ImmutableArray<string>.Empty, embedInteropTypes: false));
            Assert.Equal(p.WithAliases(ImmutableArray<string>.Empty), new MetadataReferenceProperties(MetadataImageKind.Assembly, default(ImmutableArray<string>), embedInteropTypes: false));
            Assert.Equal(p.WithAliases(new string[0]), new MetadataReferenceProperties(MetadataImageKind.Assembly, default(ImmutableArray<string>), embedInteropTypes: false));
            Assert.Equal(p.WithAliases(new[] { "foo", "aaa" }), new MetadataReferenceProperties(MetadataImageKind.Assembly, ImmutableArray.Create("foo", "aaa"), embedInteropTypes: false));
            Assert.Equal(p.WithEmbedInteropTypes(true), new MetadataReferenceProperties(MetadataImageKind.Assembly, ImmutableArray.Create("a"), embedInteropTypes: true));

            var m = new MetadataReferenceProperties(MetadataImageKind.Module);
            Assert.Equal(m.WithAliases(default(ImmutableArray<string>)), new MetadataReferenceProperties(MetadataImageKind.Module, default(ImmutableArray<string>), embedInteropTypes: false));
            Assert.Equal(m.WithEmbedInteropTypes(false), new MetadataReferenceProperties(MetadataImageKind.Module, default(ImmutableArray<string>), embedInteropTypes: false));
        }

            internal Snapshot(VisualStudioMetadataReferenceManager provider, MetadataReferenceProperties properties, string fullPath)
                : base(properties, fullPath)
            {
                Contract.Requires(Properties.Kind == MetadataImageKind.Assembly);
                _provider = provider;

                try
                {
                    _timestamp = FileUtilities.GetFileTimeStamp(this.FilePath);
                }
                catch (IOException e)
                {
                    // Reading timestamp of a file might fail. 
                    // Let's remember the failure and report it to the compiler when it asks for metadata.
                    _error = e;
                }
            }

        public VisualStudioMetadataReference(
            VisualStudioMetadataReferenceManager provider,
            IVisualStudioHostProject hostProject,
            string filePath,
            MetadataReferenceProperties properties)
        {
            Contract.ThrowIfTrue(properties.Kind != MetadataImageKind.Assembly);

            _provider = provider;
            _hostProject = hostProject;
            _properties = properties;

            // We don't track changes to netmodules linked to the assembly.
            // Any legitimate change in a linked module will cause the assembly to change as well.
            _fileChangeTracker = new FileChangeTracker(provider.FileChangeService, filePath);
            _fileChangeTracker.UpdatedOnDisk += OnUpdatedOnDisk;
            _fileChangeTracker.StartFileChangeListeningAsync();
        }

        public void Constructor()
        {
            var m = new MetadataReferenceProperties();
            Assert.True(m.Aliases.IsDefault);
            Assert.False(m.EmbedInteropTypes);
            Assert.Equal(MetadataImageKind.Assembly, m.Kind);

            m = new MetadataReferenceProperties(MetadataImageKind.Assembly, aliases: ImmutableArray.Create("\\/[.'\":_)??\t\n*#[email protected]^%*&)", "foo"), embedInteropTypes: true);
            AssertEx.Equal(new[] { "\\/[.'\":_)??\t\n*#[email protected]^%*&)", "foo" }, m.Aliases);
            Assert.True(m.EmbedInteropTypes);
            Assert.Equal(MetadataImageKind.Assembly, m.Kind);

            m = new MetadataReferenceProperties(MetadataImageKind.Module);
            Assert.True(m.Aliases.IsDefault);
            Assert.False(m.EmbedInteropTypes);
            Assert.Equal(MetadataImageKind.Module, m.Kind);

            Assert.Equal(MetadataReferenceProperties.Module, new MetadataReferenceProperties(MetadataImageKind.Module, ImmutableArray<string>.Empty, false));
            Assert.Equal(MetadataReferenceProperties.Assembly, new MetadataReferenceProperties(MetadataImageKind.Assembly, ImmutableArray<string>.Empty, false));
        }

        protected PortableExecutableReference(
            MetadataReferenceProperties properties,
            string fullPath = null,
            DocumentationProvider initialDocumentation = null)
            : base(properties)
        {
            // TODO: remove full path normalization
            if (fullPath != null)
            {
                CompilerPathUtilities.RequireAbsolutePath(fullPath, "fullPath");

                try
                {
                    this.fullPath = Path.GetFullPath(fullPath);
                }
                catch (Exception e)
                {
                    throw new ArgumentException(e.Message, "fullPath");
                }
            }

            this.lazyDocumentation = initialDocumentation;
        }

        protected int AddMetadataReferenceAndTryConvertingToProjectReferenceIfPossible(string filePath, MetadataReferenceProperties properties)
        {
            AssertIsForeground();

            // If this file is coming from a project, then we should convert it to a project reference instead
            if (this.CanConvertToProjectReferences && ProjectTracker.TryGetProjectByBinPath(filePath, out var project))
            {
                var projectReference = new ProjectReference(project.Id, properties.Aliases, properties.EmbedInteropTypes);
                if (CanAddProjectReference(projectReference))
                {
                    AddProjectReference(projectReference);
                    AddMetadataFileNameToConvertedProjectReference(filePath, projectReference);
                    return VSConstants.S_OK;
                }
            }

            // regardless whether the file exists or not, we still record it. one of reason
            // we do that is some cross language p2p references might be resolved
            // after they are already reported as metadata references. since we use bin path
            // as a way to discover them, if we don't previously record the reference ourselves,
            // cross p2p references won't be resolved as p2p references when we finally have
            // all required information.
            //
            // it looks like
            //    1. project system sometimes won't guarantee build dependency for intellisense build
            //       if it is cross language dependency
            //    2. output path of referenced cross language project might be changed to right one
            //       once it is already added as a metadata reference.
            //
            // but this has one consequence. even if a user adds a project in the solution as
            // a metadata reference explicitly, that dll will be automatically converted back to p2p
            // reference.
            //
            // unfortunately there is no way to prevent this using information we have since,
            // at this point, we don't know whether it is a metadata reference added because
            // we don't have enough information yet for p2p reference or user explicitly added it
            // as a metadata reference.
            AddMetadataReferenceCore(this.MetadataReferenceProvider.CreateMetadataReference(this, filePath, properties));

            // here, we change behavior compared to old C# language service. regardless of file being exist or not,
            // we will always return S_OK. this is to support cross language p2p reference better.
            //
            // this should make project system to cache all cross language p2p references regardless
            // whether it actually exist in disk or not.
            // (see Roslyn bug 7315 for history - http://vstfdevdiv:8080/DevDiv_Projects/Roslyn/_workitems?_a=edit&id=7315)
            //
            // after this point, Roslyn will take care of non-exist metadata reference.
            //
            // But, this doesn't sovle the issue where actual metadata reference
            // (not cross language p2p reference) is missing at the time project is opened.
            //
            // in that case, msbuild filter those actual metadata references out, so project system doesn't know
            // path to the reference. since it doesn't know where dll is, it can't (or currently doesn't)
            // setup file change notification either to find out when dll becomes available.
            //
            // at this point, user has 2 ways to recover missing metadata reference once it becomes available.
            //
            // one way is explicitly clicking that missing reference from solution explorer reference node.
            // the other is building the project. at that point, project system will refresh references
            // which will discover new dll and connect to us. once it is connected, we will take care of it.
            return VSConstants.S_OK;
        }